Migration Information

For teams migrating from the V1 to V2 component, please refer to the migration guide for changes to the component.

Component Guide

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.

Note: 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.

Note: 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 Mozilla 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';

Note: 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 here for more information.

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

When mask:"numeric", the maskConfig prop accepts NumericFormatProps.

For all other mask types, maskConfig will accept PatternFormatProps.

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

Please visit the Pattern Format and Numeric Format for detailed documentation on all available configuration settings.

Phone

Date

Zip

Social Security Number

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	Required	Description
autoComplete	string	'off'	-	Autocomplete configuration for the input field See the Mozilla Developer Network docs for more information
className	string	-	-	CSS class name to apply to each element within the component
clearButtonRef	React.RefObject<HTMLButtonElement>	-	-	Use to pass a ref to the clear input button
css	Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>>	-	-	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	-	-	Suffix used to create a unique ID used for automated testing See Component Testing for more information
disableDefaultProviderProps	boolean	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	'_'	-	The character to use in the mask; only used if mask is defined
errorMessage	string | never	-	-	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	-	-	Function to format the input value when the value changes
helper	React.ReactNode	-	-	Helper element next to label
hideLabel	boolean	false	-	If true, the label will be visually hidden
highlighted	boolean	false	-	If true, the input field will be highlighted
inputLeftElement	{ element: React.ReactNode; description?: string | undefined; }	-	-	Content to be displayed as a left element within the input (typically a IconSymbol)
isClearable	boolean	-	-	If true, the input will display a clear button
isDisabled	boolean	false	-	If true, the input will be disabled
isOptional	boolean	false	-	If true, the label will be appended with "(Optional)"
isReadOnly	boolean	false	-	If true, the input will be read-only
isRequired	boolean | never	-	-	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
leftAddOn	React.ReactNode	-	-	Content to display in the left add-on
leftAddOnDescription	string	-	-	Screen reader text for the left add-on
mask	"numeric" | string	-	-	The type of mask to apply to the input field
maskConfig	NumericFormatProps | PatternFormatProps	-	-	Mask configuration for the input field NumericFormatProps is only used when mask is 'numeric' PatternFormatProps is used when mask is not 'numeric' (e.g., 'phone', 'ssn', 'date', 'zip', or any custom mask string you define). See the Numeric Format for more information. See the Pattern Format for more information.
maxLength	number	-	-	The maximum number of characters allowed in the input field
model	never | string	-	-	model should not exist in useState mode. Model name for form validation. Only used when in a FormProvider.
onBlur	React.FocusEventHandler<HTMLInputElement>	-	-	Callback function executed when the input is blurred
onChange	React.ChangeEventHandler<HTMLInputElement>	-	-	Callback function executed when the input value changes
onClear	() => void	-	-	Callback function executed when the input is cleared
onFocus	React.FocusEventHandler<HTMLInputElement>	-	-	Callback function executed when the input is focused
onKeyDown	React.KeyboardEventHandler<HTMLInputElement>	-	-	Callback function executed when a key is pressed within TextInput
onPaste	React.ClipboardEventHandler<HTMLInputElement>	-	-	Callback function executed when a value is pasted into the TextInput
placeholder	string	-	-	Input placeholder text
prefix	string | React.ReactElement<any, string | React.JSXElementConstructor<any>>	-	-	Text to display before the input field
preserveWhitespace	boolean	false	-	If true, preserve leading and trailing whitespace
requirementConfig	RequirementConfigType	-	-	Configuration used to display password requirements; primarily used when type is 'password'
returnMaskAsNumber	boolean	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	false	-	If true, the value of the TextInput will be returned to the FormProvider or state value unmasked
rightAddOn	React.ReactNode	-	-	Content to display in the right add-on
rightAddOnDescription	string	-	-	Screen reader text for the right add-on
subText	string | { text: string; position: SubTextPosition; }	-	-	Additional descriptive text for the input
successMessage	string	-	-	Success message to display for the input
suffix	string	-	-	Text to display after the input field
validators	never | RegisterOptions	-	-	validators should not exist in useState mode. Validators for the input. Only used when in a FormProvider.
value	ValueType | never	-	-	The value of the input. Only used when not in a FormProvider. value should not exist in useForm mode.
width	string	'100%'	-	The width of the TextInput

Below are the link(s) to the relevant GitHub type files:

Abyss.d.ts

TextInput.types.ts

FormInputRequirementWidget.types.ts

FormInput.types.ts

TextInput Classes

Class Name	Description
.abyss-text-input	TextInput input element
.abyss-text-input-root	TextInput root element
.abyss-text-input-label	FormInput label
.abyss-text-input-clear	FormInput clear
.abyss-text-input-prefix	TextInput prefix
.abyss-text-input-suffix	TextInput suffix
.abyss-text-input-left-element	TextInput left 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-descriptors	Descriptor for FormInput
.abyss-text-input-left-add-on	Content for Left AddOn
.abyss-text-input-right-add-on	Content for Right AddOn
.abyss-text-input-elements-container	Container for all elements
.abyss-text-input-container-wrapper	Container that wraps the elements / addons
.abyss-text-input-requirement-widget	Wrapper for password requirements
.abyss-text-input-sub-text	Subtext element

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 pattern.

Multi-Step Messaging

Textbox 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.

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

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

Search tokens

TextInput 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.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

Search tokens

Add Ons 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

Search tokens

Header 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

Search tokens

Validation 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

Search tokens

Pass Requirement 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