Skip to main content

Input

The Input component is used to get user input in a text field.

Import#

import { Input } from "pearl-ui";

Usage#

<Input  placeholder="This is a text input field"  onChangeText={(newValue) => console.log(newValue)}/>

Input sizes#

Use the size prop to change the size of the input field. You can set the value to the keys available in PearlTheme.components.Input["sizes"], which are "xs", "s", "m", and "l" in the default theme.

<Input  size="xs"  placeholder="This is an xs input"/>
<Input  size="s"  placeholder="This is an s input"/>
<Input  size="m"  placeholder="This is an m input"/>
<Input  size="l"  placeholder="This is an l input"/>

Input variants#

Use the variant prop to change the visual style of the input field. You can set the value to the keys available in PearlTheme.components.Input["variants"], which are "filled" and "outline" in the default theme.

<Input  variant="filled"  placeholder="This is the filled input"/>
<Input  variant="outline"  placeholder="This is the outlines input"/>

Input color scheme#

Use the colorScheme prop to change the color palette of the input field. This is much more powerful than simply passing a backgroundColor style prop as the colorScheme prop changes all the use color values in a palette through a single prop.

You can set the value only to the keys available in PearlTheme.palette that contain a palette of colors represented as an object, which are "primary", "secondary", "neutral", etc in the default Pearl theme.

<Input  colorScheme="primary"  placeholder="This is the primary input"/>
<Input  colorScheme="secondary"  placeholder="This is the secondary input"/>

Input with icon#

You can add left and right icons to Input using the leftIcon and rightIcon props respectively.

info

The leftIcon and rightIcon prop values should be React elements, NOT strings.

import { Icon } from "pearl-ui";
<Input  placeholder="Enter some value"  leftIcon={<Icon iconFamily="Ionicons" iconName="md-lock-closed" />}/>
<Input  placeholder="Enter some value"  rightIcon={<Icon iconFamily="Ionicons" iconName="ios-eye" />}/>

Input with clear button#

For certain use cases, you might want to provide your users with the option to clear the input field by pressing a button. You can easily achieve this with Input with the help of the hasClearButton prop.

import { Icon } from "pearl-ui";
<Input placeholder="Enter some value" hasClearButton />;

Input focus state#

The input field is in a focus state when the text inside the field can be edited. Input allows you to update the visual style of the input field when it is focused using some special props prefixed with the word focus.

<Input  focusBackgroundColor="cyan"  focusBorderColor="violet"  onFocus={() => console.log("Field was focused!")}/>

Input error state#

Similar to the focus state, you can add an error state to the input field based on any validation criteria you use along with special visual styles to go along with it by using some special props prefixed with the word error. The isInvalid prop is used to define whether the input field has an error or not.

You can also pass the errorMessage prop to add a helper text describing the error below the input field.

<Input  isInvalid={true}  errorMessage="Some weird error occured!"  errorBackgroundColor="pink"  errorBorderColor="red"/>

Override Style#

The Input component also supports a variety of style props which can be used to override the pre-defined variant style in the theme. Manual style props passed into the component have a higher precedance than the default component config.

// passing style prop marginTop="l" adds a top margin to the input field// passing style prop backgroundColor="xl" overrides the default component config value of backgroundColor="neutral.200"<Input variant="filled" marginTop="l" backgroundColor="green" />

Example#

Accessibility#

  • Input has the role of text field.
  • When Input is disabled, it is reflected as disabled in screen readers.
  • Input has the default accessibility label set as the placeholder value passed into it. A custom label can be specified using the accessibilityLabel prop.

Props#

Supported style props#

Input composes the Box component, you can pass all Box props to it.

Additional props#

Input also composes the TextInput component from React Native, therefore all of it's props are supported in addition to the props given below:

NameRequiredTypeDefaultDescription
sizefalsePearlTheme.components.Input["sizes"]"m"Size of the input field.
variantfalsePearlTheme.components.Input["variants"]"filled"Variant of the input field.
isDisabledfalsebooleanfalseWhether the input field is disabled.
isFullWidthfalsebooleanfalseWhether the input field should span the entire width of the parent container.
isInvalidfalsebooleanfalseWhether there the input field is in an error state.
errorMessagefalsestringThe error message to be displayed if the input field is in an error state.
colorSchemefalsePearlTheme["palette"]"primary"Active color palette of the input field.
hasClearButtonfalsebooleanfalseWhether the input field should display a clear button.
leftIconfalseReact.ReactElementnullIcon to display on the left side of the main text.
rightIconfalseReact.ReactElementnullIcon to display on the right side of the main text.
placeholderTextColorfalsePearlTheme["palette"]"neutral.500"Custom color of the placeholder text string.
selectionColorfalsePearlTheme["palette"]"primary.500"Custom color of the highlight and cursor color.
focusBackgroundColorfalsePearlTheme["palette"]"neutral.50"The background color of the input field when it is in focus.
focusBorderColorfalsePearlTheme["palette"]"primary.500"The border color of the input field when it is in focus.
focusBorderStartColorfalsePearlTheme["palette"]The border start color of the input field when it is in focus.
focusBorderEndColorfalsePearlTheme["palette"]The border end color of the input field when it is in focus.
focusBorderTopColorfalsePearlTheme["palette"]The border top color of the input field when it is in focus.
focusBorderLeftColorfalsePearlTheme["palette"]The border left color of the input field when it is in focus.
focusBorderRightColorfalsePearlTheme["palette"]The border right color of the input field when it is in focus.
focusBorderBottomColorfalsePearlTheme["palette"]The border bottom color of the input field when it is in focus.
focusShadowColorfalsePearlTheme["palette"]The shadow color of the input field when it is in focus.
errorBackgroundColorfalsePearlTheme["palette"]The background color of the input field when it is in an error state.
errorBorderColorfalsePearlTheme["palette"]"danger.500"The border color of the input field when it is in an error state.
errorBorderStartColorfalsePearlTheme["palette"]The border start color of the input field when it is in an error state.
errorBorderEndColorfalsePearlTheme["palette"]The border end color of the input field when it is in an error state.
errorBorderTopColorfalsePearlTheme["palette"]The border top color of the input field when it is in an error state.
errorBorderLeftColorfalsePearlTheme["palette"]The border left color of the input field when it is in an error state.
errorBorderRightColorfalsePearlTheme["palette"]The border right color of the input field when it is in an error state.
errorBorderBottomColorfalsePearlTheme["palette"]The border bottom color of the input field when it is in an error state.
errorShadowColorfalsePearlTheme["palette"]The shadow color of the input field when it is in an error state.

Default component Config#

export default {  parts: ["root", "input", "text", "icon", "errorText"],  baseStyle: {    root: {      flexDirection: "row",      alignSelf: "flex-start",      my: "2xs",      focusBorderColor: "primary.500",      errorBorderColor: "danger.500",      errorMessageColor: "danger.500",    },    text: {      color: {        light: "neutral.900",        dark: "neutral.50",      },      fontFamily: "Poppins-Regular",      fontWeight: "400",    },    icon: {      alignSelf: "center",      color: {        light: "neutral.400",        dark: "neutral.600",      },    },    input: {      placeholderTextColor: {        light: "neutral.500",        dark: "neutral.600",      },    },    errorText: {      variant: "caption",      color: "danger.500",      marginBottom: "2xs",    },  },  sizes: {    xs: {      root: {        py: "2xs",        px: "xs",        borderRadius: "s",      },      text: {        variant: "btn4",      },      input: {        mx: "2xs",      },      icon: {        size: "s",      },    },    s: {      root: {        py: "xs",        px: "xs",        borderRadius: "s",      },      input: {        mx: "2xs",      },      text: {        variant: "btn3",      },      icon: {        size: "s",      },    },    m: {      root: {        py: "s",        px: "s",        borderRadius: "m",      },      input: {        mx: "xs",      },      text: {        variant: "btn2",      },      icon: {        size: "m",      },    },    l: {      root: {        py: "m",        px: "s",        borderRadius: "m",      },      input: {        mx: "xs",      },      text: {        variant: "btn1",      },      icon: {        size: "m",      },    },  },  variants: {    filled: {      root: {        backgroundColor: {          light: "neutral.200",          dark: "neutral.900",        },        focusBackgroundColor: {          light: "neutral.50",          dark: "neutral.800",        },        borderWidth: 1,        borderColor: {          light: "neutral.200",          dark: "neutral.900",        },      },    },    outline: {      root: {        backgroundColor: {          light: "neutral.50",          dark: "neutral.800",        },        borderWidth: 1,        borderColor: {          light: "neutral.300",          dark: "neutral.600",        },      },      input: {        placeholderTextColor: {          light: "neutral.400",          dark: "neutral.500",        },        selectionColor: "primary.500",        allowFontScaling: true,      },      icon: {        color: {          light: "neutral.400",          dark: "neutral.500",        },      },    },  },  defaults: {    size: "m",    variant: "filled",  },};