import { InputField } from '@uhg-abyss/mobile';() => { const form = useForm();
return ( <FormProvider state={form}> <InputField model="input-field-sandbox" label="Sandbox Label" hintText="Sandbox Hint Text" /> </FormProvider> );};If the InputField is inside a ScrollView, verify the keyboardShouldPersistTaps prop on the ScrollView is set to "always" or "handled" to allow pressing icons within the InputField when the keyboard is open.
useForm (recommended)
Using the useForm hook with FormProvider sets state for the component.
useState
Using the useState hook gets values from the component state.
Placeholder
Use the placeholder prop to give users a short description in the input field before they enter a value.
Label
Use the label prop to display a label above the input.
Error Message (useState)
Use the errorMessage prop to display a custom error message below the input field when using useState.
Success Message
Use the successMessage prop to display a custom success message below the input field.
Disabled
Set the isDisabled prop to true to disable the input field so users cannot enter a value.
Types
Use the type prop to set the type of input field to be displayed. Types include: 'text', 'email', 'password', 'price', 'number' and 'phone'.
The default is text.
Text
Password
Price
Prefix
Use the prefix prop to display content before the input field. This is meant for text and decorative icons. The default prefix for type='price' is '$'.
Suffix
Use the suffix prop to display content after the input field.
Action Icon
Use the actionIcon prop to pass in an actionable button. This can be used to further customize the input component.
Validation
Use the validations prop to set rules for the field to be valid. Each validation must have a key for it's name and an object that describes the validation. The object must have a message to display what should be validated. To create a custom validation, you can add a validate function that takes in the text as an argument and should return a boolean.
There are 5 built in validations: minLength, maxLength, hasUppercaseLetters, hasLowercaseLetters and hasNumbers. For the minLength and maxLength validations, you can pass in a value to determine the amount of characters to check for.
- minLength - Returns true if the amount of characters is less than the value. Default: 8
- maxLength - Returns true if the amount of characters is less than the value. Default: 20
- hasUppercaseLetters - Returns true if the text contains uppercase letters.
- hasLowercaseLetters - Returns true if the text contains lowercase letters.
- hasNumbers - Returns true if the text contains numbers.
To check the status of the validations, use the second parameter of the onChangeText prop.
Help Content
Use the helpContent prop to display a help icon in the top right of the container, which will display the provided content in a modal screen when pressed.
InputField Props
| Name | Type | Default | A11y | Description |
|---|---|---|---|---|
actionIcon | string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | null | undefined | Sets the action button to be displayed after the text entry field | ||
errorMessage | string | undefined | Error message to be displayed below input field | ||
helpButtonAccessibilityLabel | string | undefined | Set the accessibility label for the help button | ||
helpContent | string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | null | undefined | When defined, displays a help icon that can be tapped to view the provided content in a modal screen | ||
hintText | string | undefined | Set the text displayed below label | ||
isDisabled | boolean | undefined | false | Flag to enable/disable the input. If true, the input will be disabled | |
isRequired | boolean | undefined | false | Flag to add an asterisk next to the label, indicating that the field is required. This is independent of form validation and is only for visual purposes. | |
keyboardType | KeyboardTypeOptions | undefined | Determines which keyboard to open | ||
label | string | undefined | Label for input field | ||
model | string | undefined | model is only used when the input is bound to a form via useForm. Model name used to bind the input to the form state. Only used inside a FormProvider. | ||
onActionIconPress | GestureResponderEventHandler | Callback fired when the action button is pressed | ||
onChangeText | ((input: string, inputValidations?: Record<string, boolean> | null | undefined) => void) | undefined | Callback that is called when the input field text changes. Changed text is passed as a single string argument to the callback handler. Additionally, it receives an object with validation rules and their results. | ||
placeholder | string | undefined | Short description displayed in the input before the user enters a value | ||
prefix | string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | null | undefined | Sets the content to be displayed before the text entry field | ||
requirementsText | string | undefined | Set the text displayed above validations | ||
showOptionalLabel | boolean | undefined | Flag to display 'optional' next to the label | ||
showValidations | boolean | undefined | true | Flag to show validations below the input field | |
successMessage | string | undefined | Success message to be displayed below input field | ||
suffix | string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | null | undefined | Sets the content to be displayed after the text entry field | ||
textContentType | "none" | "password" | "name" | "dateTime" | "URL" | "addressCity" | "addressCityAndState" | "addressState" | "countryName" | "creditCardNumber" | "creditCardExpiration" | "creditCardExpirationMonth" | ... 34 more ... | undefined | Give the keyboard and the system information about the expected semantic meaning for the content that users enter. | ||
type | InputType | undefined | 'text' | Set the type of input field | |
validations | RegisterOptions | Validations | undefined | Set rules for the input to be valid. Valid in both useState and useForm modes. Set rules for the input to be valid. | ||
value | string | undefined | The value to show for the text input. TextInput is a controlled component, which means the native value will be forced to match this value prop if provided. For most uses this works great, but in some cases this may cause flickering - one common cause is preventing edits by keeping value the same. In addition to simply setting the same value, either set editable={false}, or set/update maxLength to prevent unwanted edits without flicker. Value of the input field |
InputField Classes
| Class Name | Description |
|---|---|
| abyss-input-field | Input container |
| abyss-input-field-cancel-button | Cancel button |
| abyss-input-field-cancel-icon | Cancel icon |
| abyss-input-field-container | The container around the input field |
| abyss-input-field-header | Header element |
| abyss-input-field-help-button | Help button |
| abyss-input-field-help-modal | Help modal |
| abyss-input-field-hint-text | Input hint text |
| abyss-input-field-icon-button | Icon button |
| abyss-input-field-label | Label element |
| abyss-input-field-message | Message element |
| abyss-input-field-prefix | Prefix text |
| abyss-input-field-requirements-text | Requirements text |
| abyss-input-field-root | Root element |
| abyss-input-field-show-password-icon | Show password icon |
| abyss-input-field-validation-checked-icon | Valid icon |
| abyss-input-field-validation-container | Validation container |
| abyss-input-field-validation-text | Validation text |
| abyss-input-field-validation-unchecked-icon | Invalid icon |
| abyss-input-help-icon | Help icon element |
| abyss-input-help-modal-close-button | Help modal close button |
| abyss-input-help-modal-footer | Help modal footer |
| abyss-input-message-icon | Message icon |
| abyss-input-message-text | Message text |
InputField Translations
| Translation Key | Value |
|---|---|
| help | Help |
| close | Close |
| error | Error |
| success | Success |
| InputField.priceInDollars | In Dollars. |
| InputField.clearText | Clear Text |
| InputField.hidePassword | Hide Password |
| InputField.revealPassword | Reveal Password |
| InputField.pass | Pass: |
Focus Guidance
Abyss does not control the focus of components on the screen when handling validation errors. The useSetFocus hook can be used for this.
For input fields, the focus should move back to the input when there is an error (e.g user typed too many characters).
InputField Tokens
| Token Name | Value | |
|---|---|---|
| input-header.color.text.label | #4B4D4F | |
| input-header.color.text.hint | #4B4D4F | |
| input-header.color.icon.help.rest | #196ECF | |
| input-header.color.icon.help.active | #004BA0 | |
| input-message.color.text.error | #990000 | |
| input-message.color.text.success | #007000 | |
| input-message.color.icon.error | #990000 | |
| input-message.color.icon.success | #007000 | |
| input-field.color.surface.default | #FFFFFF | |
| input-field.color.surface.disabled | #F3F3F3 | |
| input-field.color.text.input | #4B4D4F | |
| input-field.color.border.rest.default | #4B4D4F | |
| input-field.color.border.rest.error | #990000 | |
| input-field.color.border.rest.success | #007000 | |
| input-field.color.border.active.default | #196ECF | |
| input-field.color.border.active.error | #990000 | |
| input-field.color.border.active.success | #007000 | |
| input-field.color.icon.utility.rest | #4B4D4F | |
| input-field.color.icon.utility.disabled | #929496 | |
| input-field.color.icon.utility.active | #323334 | |
| input-requirements.color.text.label.header | #4B4D4F | |
| input-requirements.color.text.label.default | #4B4D4F | |
| input-requirements.color.text.label.success | #007000 | |
| input-requirements.color.icon.default | #4B4D4F | |
| input-requirements.color.icon.success | #007000 | |
| input-field.border-radius.all.container | 4 | |
| input-field.border-width.all.container.rest | 1 | |
| input-field.border-width.all.container.active | 3 | |
| input-header.sizing.all.icon.help | 24 | |
| input-message.sizing.all.icon.leading | 20 | |
| input-field.sizing.icon.all.utility | 20 | |
| input-field.sizing.icon.all.picker | 20 | |
| input-requirements.sizing.all.icon.leading | 16 | |
| input-container.spacing.gap.vertical.container | 8 | |
| input-header.spacing.gap.horizontal.container | 12 | |
| input-header.spacing.gap.horizontal.label | 4 | |
| input-header.spacing.gap.vertical.content | 4 | |
| input-message.spacing.gap.horizontal.container | 4 | |
| input-field.spacing.padding.all.field | 12 | |
| input-field.spacing.gap.horizontal.field | 12 | |
| input-field.spacing.gap.horizontal.input-indicator | 2 | |
| input-field.spacing.gap.horizontal.prefix-input | 2 | |
| input-requirements.spacing.gap.vertical.container | 8 | |
| input-requirements.spacing.gap.vertical.requirements-list | 8 | |
| input-requirements.spacing.gap.horizontal.requirement | 8 | |
| input-field.box-shadow.container.active |
| |
| input-field.box-shadow.container.error |
| |
| input-field.box-shadow.container.success |
|