Usage

import { TextField } from "@opengovsg/oui"

<TextField label="Full name" />

The TextField component provides a single-line text input with built-in label, description, and error message support. It is built on React Aria's TextField.

If the component does not have a visible label (by passing a label prop), an aria-label or aria-labelledby prop must be passed instead to identify it to assistive technology.

Examples

With Label and Description

Provide clear instructions to users with labels and descriptions.

With Placeholder

Use the inputProps.placeholder to show placeholder text.

With Error Message

Combine isInvalid and errorMessage props to show validation errors.

Sizes

Use the size prop to change the size of the text field. Defaults to "md".

Controlled

Use the value and onChange props to control the text field value programmatically.

Disabled

Use the isDisabled prop to disable the text field.

Read Only

Use the isReadOnly prop to make the text field read-only. The value can be selected but not modified.

Validation

TextField supports React Aria's form validation system:

• Built-in constraints: Use isRequired, minLength, maxLength, pattern, or type (e.g., "email", "url") for native HTML validation. Errors display after the user commits a value or submits the form.
• Custom validation: Use the validate prop to provide a function that returns an error message string, or null/true if valid.
• Realtime validation: Use the isInvalid prop with errorMessage for immediate feedback as the user types.
• Validation behavior: The validationBehavior prop controls enforcement — "native" (default) prevents form submission when invalid, while "aria" only marks the field via ARIA attributes and allows submission.

Events

TextField supports the following event handlers, inherited from React Aria's TextField:

• onFocus / onBlur — Called when the input gains or loses focus.
• onFocusChange — Called when the focus state changes, receiving a boolean.
• onChange — Called when the text value changes, receiving the new string value.
• onCopy / onCut / onPaste — Called on clipboard operations.
• onCompositionStart / onCompositionEnd — Called during IME composition for internationalized text input.
• onKeyDown / onKeyUp — Called on keyboard events.
• onSelect — Called when text is selected within the input.

Accessibility

• Built with a native <input> element for full browser and assistive technology support.
• Label, description, and error message are automatically linked to the input via aria-labelledby and aria-describedby.
• Required and invalid states are exposed to assistive technology.
• Supports keyboard interaction: text entry, clipboard shortcuts, and standard input navigation.
• If no visible label is provided, an aria-label or aria-labelledby prop must be set.

Slots

• base: The root container wrapper.
• label: The label text element.
• input: The input element.
• description: The description text below the field.
• error: The error message text.

Custom Styles

You can customize the TextField component by passing custom Tailwind CSS classes to the component slots via the classNames prop.

Props

TextField