TextInput | Abyss

import { TextInput } from '@uhg-abyss/web/ui/TextInput';

subText

width

prefix

suffix

mask

type

hideLabel

isClearable

isDisabled

highlighted

() => {
  const [value, setValue] = useState('');

  return (
    <TextInput
      label="TextInput Sandbox"
      value={value}
      isClearable
      onChange={(e) => setValue(e.target.value)}
    />
  );
};

Form integration

useForm (recommended)

Using useForm and FormProvider simplifies form management by providing out-of-the-box validation, form state handling, and performance optimizations, leveraging the power of react-hook-form.

useState

Using the useState hook gets values from the component state.

Display properties

Label

Use the label prop to display a label above the input. To hide the input label, set hideLabel to true.

Use isRequired and isOptional for further customization.

useState only

If using useForm, do not use isRequired. The same functionality can be achieved with required: true in validators.

Helper

Use the helper prop to display a help icon next to the label. Simply passing a string value will render the default helper, a Tooltip containing that string. The helper can be customized by passing in a node. It is recommended to use either a Tooltip or a Popover. See When should I use a Tooltip vs. a Popover? for more information on best practices regarding the two.

Prefix and suffix

Use the prefix and suffix props to display helpful text within the input field.

Subtext

Use the subText prop to display helpful information related to the input field. The prop accepts either a string or an object of the form:

{
  text: string;
  position: 'above' | 'below';
}

The position property determines where the subtext will be displayed in relation to the input field. The default value is 'below'.

Width

Use the width prop to set the width of the input field.

Left element

Use the inputLeftElement prop to add an element inside of the text input field. The recommended usage is for inserting icons. The prop accepts an object with the following properties:

element: The element to be displayed inside the input field.
description: An optional string that describes the purpose of the element for screen readers.

These are considered decorative and do not need to be exposed to screen readers. That said, please note that icons should not provide any information that is not also conveyed in a screen-readable way. For example, an exclamation mark (!) icon to indicate errors needs to be accompanied by aria-invalid.

If the icon is used to convey additional information, use the inputLeftElement.description prop to provide a description for screen readers.

Add-ons

Use the leftAddOn and rightAddOn props to add add-ons to the outside of the text input field. The recommended usage is for inserting supplemental text.

It is recommended to use the leftAddOnDescription and rightAddOnDescription props to communicate the purpose of the add-ons to screen reader users.

Validation

Validators (useForm)

Form Compatibility

useState

useForm

Use the validators prop to set validation rules for the field when using useForm. See the examples below for implementation on various types of validation.

Tip

The default error message when required is true is minimally acceptable for accessibility. It is highly recommended to customize it to be more specific to the use of the field and form.

Error message (useState)

Form Compatibility

useState

useForm

Use the errorMessage prop to display a custom error message below the input field when using useState.

Success message

Form Compatibility

useState

useForm

Use the successMessage prop to display a custom success message below the input field. To provide a single success message across all form input components using useForm/FormProvider, you can provide successMessage to FormProvider as shown here.

Highlighted

Form Compatibility

useState

useForm

Use the highlighted prop to enable a distinct background color when fields are required. To supply this across all form input components using useForm/FormProvider, you can provide highlighted to FormProvider as shown here.

Interactivity

Clearable

Set the isClearable prop to true to display a clear button in the input field. The optional onClear callback prop can be used to trigger additional actions when the clear button is clicked.

Disabled

Set the isDisabled prop to true to disable the input field, so users cannot enter a value.

Max length

Use the maxLength prop to limit the number of characters allowed in the input field.

Note

Default values created in useForm() can be longer than maxLength. It currently only applies to inputted values after initial load.

Auto complete

Use the autoComplete prop whenever you are collecting information about the user. Head to Mozillaopens in a new window to find all of the autocomplete options.

Formatter

Use the formatter prop to format values on change for text inputs.

Types

Use the type prop to set the type of input field to be displayed. Types include: 'text', 'email', 'tel' and 'password'. The default value is 'text'.

Text

Password

Multi-step password validation

Use the requirementConfig prop to display password requirements.

The requirementConfig prop is an object that takes in two props, title and items.

title : The title for the password requirements.
items : An array of objects that define the password requirements. Each object in the array has three properties: variant, test, and text.
- variant : This property can be 'success', 'default', or 'error' . It is used to determine the style of the requirement message.
- text : This property is the actual text of the requirement message.
- test : This property requires a function that will be used to evaluate the password input. The function should return a boolean value, with true indicating that the password meets the requirement, and false indicating that it does not.

Here's an example of how to use the requirementConfig prop:

const requirementConfig = {
  title: 'Password must have at least:',
  items: [
    {
      test: (pwd) => /[A-Z]/.test(pwd),
      text: '1 capital letter',
      variant: 'default',
    },
    {
      test: (pwd) => /[a-z]/.test(pwd),
      text: '1 lower case letter',
      variant: 'default',
    },
    {
      test: (pwd) => /[0-9]/.test(pwd),
      text: '1 number',
      variant: 'default',
    },
    {
      test: (pwd) => /[!@#$%^&*()_+\-=\[\]{};':"\\|,.<>\/?]+/.test(pwd),
      text: '1 special character',
      variant: 'default',
    },
    {
      test: (pwd) => pwd && pwd.length >= 8,
      text: '8 characters',
      variant: 'default',
    }
  ],
}
/>

To import the types for the requirementConfig prop, use can use the following:

import {
  RequirementConfigType,
  RequirementItemType,
} from '@uhg-abyss/web/ui/TextInput';

Info

Teams will need to handle all validation logic for determining password requirements. Refer to our Validation section for implementation examples.

Masks

Use the mask prop to set the masking variation of the input field. Default masks available: 'phone', 'date', 'zip', 'numeric', and 'ssn'.

While the use of a placeholder is generally not recommended, masking is one instance it can be used. See hereopens in a new window for more information.

Further configuration can be set by usage of the maskConfig prop, which utilizes the react-number-formatopens in a new window library to take in an object of additional props.

When mask:"numeric", the maskConfig prop accepts NumericFormatPropsopens in a new window.

For all other mask types, maskConfig will accept PatternFormatPropsopens in a new window.

// Numeric mask example
{
  mask: 'numeric',
  maskConfig: NumericFormatProps = {
    thousandSeparator: ',',
    allowLeadingZeros: true,
  }
}
// Pattern mask example
{
  mask: 'time',
  maskConfig: PatternFormatProps{
    format: '##:##:##',
  }
}

Please visit the Pattern Formatopens in a new window and Numeric Formatopens in a new window for detailed documentation on all available configuration settings.

Phone

Date

Zip

Numeric

Currency

Return unmasked value

Use the returnUnmaskedValue prop to return an unmasked value.

Empty mask character

Use the emptyMaskChar prop to replace the empty mask placeholder.

Custom mask patterns

Pass in a custom pattern into the mask prop to create unique masks. The hash string, #, allows number inputs in place of the hash.

Note

Providing a custom mask will use PatternFormatProps for the maskConfig prop.

Custom time mask

TextInput Props

Name	Type	Default	Description
autoComplete	string \| undefined	'off'	Autocomplete configuration for the input field See the Mozilla Developer Network docsopens in a new window for more information
className	string \| undefined		CSS class name to apply to each element within the component
clearButtonRef	RefObject<HTMLButtonElement> \| undefined		Use to pass a ref to the clear input button
css	CSSProperties \| Partial<Record<"abyss-text-input-clear" \| "abyss-text-input" \| "abyss-text-input-label" \| "abyss-text-input-root" \| "abyss-text-input-prefix" \| "abyss-text-input-sub-text" \| ... 9 more ... \| "abyss-text-input-requirement-widget", CSSProperties>> \| undefined		Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation See CSS Prop Styling for more information
data-testid	string \| undefined		Suffix used to create a unique ID used for automated testing See Component Testing for more information
disableDefaultProviderProps	boolean \| undefined	false	If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored.
emptyMaskChar	string \| undefined	'_'	The character to use in the mask; only used if mask is defined
errorMessage	string \| undefined		Error message to display for the input. Only used when not in a FormProvider. errorMessage should not exist in useForm mode.
formatter	((value: string) => string) \| undefined		Function to format the input value when the value changes
helper	string \| number \| bigint \| boolean \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| Promise<...> \| null \| undefined		Helper element next to label
hiddenFrom	Breakpoint \| undefined		When defined, the component is hidden once the screen width reaches the specified breakpoint.
hideLabel	boolean \| undefined	false	If true, hides the label visually while keeping it accessible to screen readers.
highlighted	boolean \| undefined	false	If true, the input field will be highlighted
inputLeftElement	{ element: ReactNode; description?: string \| undefined; } \| undefined		Content to be displayed as a left element within the input (typically a IconSymbol)
isClearable	boolean \| undefined		If true, the input will display a clear button
isDisabled	boolean \| undefined	false	If true, the input will be disabled
isOptional	boolean \| undefined	false	If true, the label will be appended with "(Optional)"
isReadOnly	boolean \| undefined	false	If true, the input will be read-only
isRequired	boolean \| undefined		Whether the input is required. Only used when not in a FormProvider. isRequired should not exist in useForm mode.
label	string		The label for the input; associated with it so screen readers announce it as the input's accessible name.
leftAddOn	string \| number \| bigint \| boolean \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| Promise<...> \| null \| undefined		Content to display in the left add-on
leftAddOnDescription	string \| undefined		Screen reader text for the left add-on
mask	string \| undefined		The type of mask to apply to the input field
maskConfig	NumericFormatProps \| PatternFormatProps \| undefined		PatternFormatProps is used when mask is not 'numeric' (e.g., 'phone', 'ssn', 'date', 'zip', or any custom mask string you define). Mask configuration for the input field NumericFormatProps is only used when mask is 'numeric' See the Pattern Formatopens in a new window for more information. See the Numeric Formatopens in a new window for more information.
maxLength	number \| undefined		The maximum number of characters allowed in the input field
model	string \| undefined		model should not exist in useState mode. Model name for form validation. Only used when in a FormProvider.
onBlur	FocusEventHandler<HTMLInputElement> \| undefined		Callback function executed when the input is blurred
onChange	ChangeEventHandler<HTMLInputElement> \| undefined		Callback function executed when the input value changes
onClear	(() => void) \| undefined		Callback function executed when the input is cleared
onFocus	FocusEventHandler<HTMLInputElement> \| undefined		Callback function executed when the input is focused
onKeyDown	KeyboardEventHandler<HTMLInputElement> \| undefined		Callback function executed when a key is pressed within TextInput
onPaste	ClipboardEventHandler<HTMLInputElement> \| undefined		Callback function executed when a value is pasted into the TextInput
placeholder	string \| undefined		Input placeholder text
prefix	string \| (string & ReactElement<any, string \| JSXElementConstructor<any>>) \| undefined		Text to display before the input field
preserveWhitespace	boolean \| undefined	false	If true, preserve leading and trailing whitespace
requirementConfig	RequirementConfigType \| undefined		Configuration used to display password requirements; primarily used when type is 'password'
returnMaskAsNumber	boolean \| undefined	false	If true, the value of the TextInput will be returned to the FormProvider or state value as a number instead of a string
returnUnmaskedValue	boolean \| undefined	false	If true, the value of the TextInput will be returned to the FormProvider or state value unmasked
rightAddOn	string \| number \| bigint \| boolean \| ReactElement<any, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| Promise<...> \| null \| undefined		Content to display in the right add-on
rightAddOnDescription	string \| undefined		Screen reader text for the right add-on
slotProps	Partial<Record<ToSlotKey<{ input: LeafSlotDef<"input", "text-input">; root: LeafSlotDef<"div", undefined>; label: LeafSlotDef<"div", undefined>; clear: WrappedSlotDef<...>; ... 11 more ...; subText: WrappedSlotDef<...>; }, "text-input">, SlotPropsLeafValue>> \| undefined		Props to pass to individual internal slots of the component. See slotProps for more information
subText	string \| { text: string; position: SubTextPosition; } \| undefined		Additional descriptive text for the input
successMessage	string \| undefined		Success message to display for the input
suffix	string \| undefined		Text to display after the input field
type	"number" \| "text" \| "email" \| "password" \| "tel" \| undefined	'text'	The type of input field
validators	RegisterOptions \| undefined		validators should not exist in useState mode. Validators for the input. Only used when in a FormProvider.
value	string \| (readonly string[] & string) \| undefined		The value of the input. Only used when not in a FormProvider. value should not exist in useForm mode.
visibleFrom	Breakpoint \| undefined		When defined, the component is hidden until the screen width reaches the specified breakpoint.
width	string \| undefined	'100%'	The width of the TextInput

TextInput Classes

Class Name	Description
.abyss-text-input	TextInput input element
.abyss-text-input-action-button	TextInput action button, often to show password
.abyss-text-input-action-button-icon	Icon inside the action button of TextInput
.abyss-text-input-clear	FormInput clear
.abyss-text-input-container-wrapper	Container that wraps the elements / addons
.abyss-text-input-descriptors	Descriptor for FormInput
.abyss-text-input-elements-container	Container for all elements
.abyss-text-input-label	FormInput label
.abyss-text-input-left-add-on	Content for Left AddOn
.abyss-text-input-left-element	TextInput left element
.abyss-text-input-prefix	TextInput prefix
.abyss-text-input-requirement-widget	Wrapper for password requirements
.abyss-text-input-right-add-on	Content for Right AddOn
.abyss-text-input-root	TextInput root element
.abyss-text-input-sub-text	Subtext element
.abyss-text-input-suffix	TextInput suffix

A combobox is a widget made up of the combination of two distinct elements: 1) a single-line textbox, and 2) an associated pop-up element for helping users set the value of the textbox. The popup may be a listbox, grid, tree, or dialog. Many implementations also include a third optional element -- a graphical button adjacent to the textbox, indicating the availability of the popup. Activating the button displays the popup if suggestions are available.

Adheres to the Combo box WAI-ARIA design patternopens in a new window.

Multi-Step Messaging

Note

The multi-step password requirement widget manages its own ARIA live region and aria-describedby behavior automatically, no additional configuration is required:

Each requirement's status (met, not met) is announced through an aria-live="polite" region on its list item, including when a previously met requirement becomes unmet again.
The requirement list and the success/error message are removed from aria-describedby as soon as the user starts typing, and restored when the field loses focus. This prevents JAWS from redundantly re-announcing the full list or message on every keystroke.

Keyboard Interactions

Key	Description
Down Arrow	If the listbox is displayed: Moves focus to the second suggested value. Note that the first value is automatically selected. If the listbox is not displayed: opens the listbox and moves focus to the first value.
Up Arrow	If the listbox is displayed, moves focus to the last suggested value. If the listbox is not displayed, opens the listbox and moves focus to the last value.
Alt + Down Arrow	Opens the listbox without moving focus or changing selection.
Enter	If the listbox is displayed and the first option is automatically selected: Sets the textbox value to the content of the selected option. Closes the listbox.
Esc	Clears the textbox. If the listbox is displayed, closes it.
Supported Keystrokes	Supported keystrokes use character matching functionality to display matched values in the Listbox.

Keyboard Interactions

Key	Description
Enter	Sets the textbox value to the content of the focused option in the listbox. Closes the listbox. Sets focus on the textbox.
Esc	Closes the listbox. Sets focus on the textbox. Clears the textbox.
Down Arrow	Moves focus to the next option. If focus is on the last option, moves focus to the first option.
Up Arrow	Moves focus to the previous option. If focus is on the first option, moves focus to the last option.
Right Arrow	Moves focus to the textbox and moves the editing cursor one character to the right.
Left Arrow	Moves focus to the textbox and moves the editing cursor one character to the left.
Home	Moves focus to the textbox and places the editing cursor at the beginning of the field.
End	Moves focus to the textbox and places the editing cursor at the end of the field.

Component Tokens

Tip

Click on the token row to copy the token to your clipboard.

TextInput Tokens

Search tokens

Token Name	Value
input.color.surface.field.default	#FFFFFF
input.color.surface.field.highlighted	#E5F8FB
input.color.surface.field.disabled	#F3F3F3
input.color.border.field.rest	#4B4D4F
input.color.border.field.hover.default	#196ECF
input.color.border.field.hover.error	#990000
input.color.border.field.hover.success	#007000
input.color.border.field.active.default	#004BA0
input.color.border.field.active.error	#990000
input.color.border.field.active.success	#007000
input.color.text.input	#4B4D4F
input.color.text.hint	#4B4D4F
input.color.text.required	#990000
input.color.icon.utility.rest	#4B4D4F
input.color.icon.utility.hover	#323334
input.color.icon.utility.active	#000000
input.color.icon.content	#323334
input.color.cursor	#196ECF
input.border-radius.all.field	4px
input.border-width.all.field.default	1px
input.border-width.all.field.active	3px
input.sizing.all.icon	20px
input.spacing.gap.vertical.container	8px
input.spacing.gap.horizontal.field	12px
input.spacing.gap.horizontal.input-indicator	2px
input.spacing.gap.horizontal.prefix-input	2px
input.spacing.gap.horizontal.suffix-clear	2px
input.spacing.padding.all.focus-container	2px
input.spacing.padding.horizontal.field	12px
input.spacing.padding.left.field	12px
input.spacing.padding.right.focus-field	44px

Add Ons Tokens

Search tokens

Token Name	Value
input-add-ons.color.surface.container	#F3F3F3
input-add-ons.color.border.container	#4B4D4F
input-add-ons.color.text	#4B4D4F
input-add-ons.border-radius.bottom-left.left	4px
input-add-ons.border-radius.top-left.left	4px
input-add-ons.border-radius.bottom-right.right	4px
input-add-ons.border-radius.top-right.right	4px
input-add-ons.border-width.all.container	1px
input-add-ons.spacing.padding.all.container	12px

Header Tokens

Search tokens

Token Name	Value
input-header.color.text.label	#4B4D4F
input-header.color.text.hint	#4B4D4F
input-header.color.icon.info.rest	#196ECF
input-header.color.icon.info.hover	#004BA0
input-header.color.icon.info.active	#002677
input-header.sizing.all.icon	24px
input-header.spacing.gap.horizontal.container	4px
input-header.spacing.gap.horizontal.label	4px
input-header.spacing.gap.vertical.content	4px
input-header.spacing.padding.top.content	2px

Validation Tokens

Search tokens

Token Name	Value
input-validation.color.surface.container	#FFFFFF
input-validation.color.text.error	#990000
input-validation.color.text.success	#007000
input-validation.color.icon.error	#990000
input-validation.color.icon.success	#007000
input-validation.sizing.all.icon	20px
input-validation.spacing.gap.horizontal.container	4px

Pass Requirement Tokens

Search tokens

Token Name	Value
input-pass-requirement.color.text.default	#4B4D4F
input-pass-requirement.color.text.met	#007000
input-pass-requirement.color.icon.default	#4B4D4F
input-pass-requirement.color.icon.met	#007000
input-pass-requirement.sizing.all.icon	16px
input-pass-requirement.spacing.gap.horizontal.container	8px

Migration Information

Form integration​

useForm (recommended)​

useState​

Display properties​

Label​

Helper​

Prefix and suffix​

Subtext​

Width​

Left element​

Add-ons​

Validation​

Validators (useForm)​

Error message (useState)​

Success message​

Highlighted​

Interactivity​

Clearable​

Disabled​

Max length​

Auto complete​

Formatter​

Types​

Text​

Password​

Multi-step password validation​

Masks​

Phone​

Date​

Zip​

Social Security Number​

Numeric​

Currency​

Return unmasked value​

Empty mask character​

Custom mask patterns​

Custom time mask​

TextInput Props​

TextInput Classes​

Multi-Step Messaging​

Keyboard Interactions​

Keyboard Interactions​

Component Tokens​

TextInput Tokens​

Add Ons Tokens​

Header Tokens​

Validation Tokens​

Pass Requirement Tokens​

Form integration

useForm (recommended)

useState

Display properties

Label

Helper

Prefix and suffix

Subtext

Width

Left element

Add-ons

Validation

Validators (useForm)

Error message (useState)

Success message

Highlighted

Interactivity

Clearable

Disabled

Max length

Auto complete

Formatter

Types

Text

Password

Multi-step password validation

Masks

Phone

Date

Zip

Social Security Number

Numeric

Currency

Return unmasked value

Empty mask character

Custom mask patterns

Custom time mask

TextInput Props

TextInput Classes

Multi-Step Messaging

Keyboard Interactions

Keyboard Interactions

Component Tokens

TextInput Tokens

Add Ons Tokens

Header Tokens

Validation Tokens

Pass Requirement Tokens