useTextField

Provides the behavior and accessibility implementation for a text field.

install	`yarn add react-aria`
version	3.23.1
usage	`import {useTextField} from 'react-aria'`

View ARIA pattern

W3C

API#

useTextField<T extends TextFieldIntrinsicElements = DefaultElementType>(
  (props: AriaTextFieldOptions<T>,
  , ref: TextFieldRefObject<T>
)): TextFieldAria<T>

Features#

Text fields can be built with <input> or <textarea> and <label> elements, but you must manually ensure that they are semantically connected via ids for accessibility. useTextField helps automate this, and handle other accessibility features while allowing for custom styling.

Built with a native <input> or <textarea> element
Visual and ARIA labeling support
Change, clipboard, composition, selection, and input event support
Required and invalid states exposed to assistive technology via ARIA
Support for description and error message help text linked to the input via ARIA

Anatomy#

Text fields consist of an input element and a label. useTextField automatically manages the relationship between the two elements using the for attribute on the <label> element and the aria-labelledby attribute on the <input> element.

useTextField also supports optional description and error message elements, which can be used to provide more context about the field, and any validation messages. These are linked with the input via the aria-describedby attribute.

useTextField returns props that you should spread onto the appropriate element:

Name	Type	Description
`inputProps`	`TextFieldInputProps<TextFieldIntrinsicElements>`	Props for the input element.
`labelProps`	`DOMAttributes \| LabelHTMLAttributes<HTMLLabelElement>`	Props for the text field's visible label element, if any.
`descriptionProps`	`DOMAttributes`	Props for the text field's description element, if any.
`errorMessageProps`	`DOMAttributes`	Props for the text field's error message element, if any.

If there is no visual label, an aria-label or aria-labelledby prop must be passed instead to identify the element to screen readers.

Example#

import type {AriaTextFieldProps} from 'react-aria';
import {useTextField} from 'react-aria';

function TextField(props: AriaTextFieldProps) {
  let { label } = props;
  let ref = React.useRef(null);
  let { labelProps, inputProps, descriptionProps, errorMessageProps } =
    useTextField(props, ref);

  return (
    <div style={{ display: 'flex', flexDirection: 'column', width: 200 }}>
      <label {...labelProps}>{label}</label>
      <input {...inputProps} ref={ref} />
      {props.description && (
        <div {...descriptionProps} style={{ fontSize: 12 }}>
          {props.description}
        </div>
      )}
      {props.errorMessage && (
        <div {...errorMessageProps} style={{ color: 'red', fontSize: 12 }}>
          {props.errorMessage}
        </div>
      )}
    </div>
  );
}

<TextField label="Email" />

import type {AriaTextFieldProps} from 'react-aria';
import {useTextField} from 'react-aria';

function TextField(props: AriaTextFieldProps) {
  let { label } = props;
  let ref = React.useRef(null);
  let {
    labelProps,
    inputProps,
    descriptionProps,
    errorMessageProps
  } = useTextField(props, ref);

  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        width: 200
      }}
    >
      <label {...labelProps}>{label}</label>
      <input {...inputProps} ref={ref} />
      {props.description && (
        <div {...descriptionProps} style={{ fontSize: 12 }}>
          {props.description}
        </div>
      )}
      {props.errorMessage && (
        <div
          {...errorMessageProps}
          style={{ color: 'red', fontSize: 12 }}
        >
          {props.errorMessage}
        </div>
      )}
    </div>
  );
}

<TextField label="Email" />

import type {AriaTextFieldProps} from 'react-aria';
import {useTextField} from 'react-aria';

function TextField(
  props:
    AriaTextFieldProps
) {
  let { label } = props;
  let ref = React.useRef(
    null
  );
  let {
    labelProps,
    inputProps,
    descriptionProps,
    errorMessageProps
  } = useTextField(
    props,
    ref
  );

  return (
    <div
      style={{
        display: 'flex',
        flexDirection:
          'column',
        width: 200
      }}
    >
      <label
        {...labelProps}
      >
        {label}
      </label>
      <input
        {...inputProps}
        ref={ref}
      />
      {props
        .description && (
        <div
          {...descriptionProps}
          style={{
            fontSize: 12
          }}
        >
          {props
            .description}
        </div>
      )}
      {props
        .errorMessage &&
        (
          <div
            {...errorMessageProps}
            style={{
              color:
                'red',
              fontSize:
                12
            }}
          >
            {props
              .errorMessage}
          </div>
        )}
    </div>
  );
}

<TextField label="Email" />

Text area#

useTextField also supports multi-line text entry with the <textarea> element via the inputElementType prop.

import type {AriaTextFieldProps} from 'react-aria';
import {useTextField} from 'react-aria';

function TextArea(props: AriaTextFieldProps) {
  let { label } = props;
  let ref = React.useRef(null);
  let { labelProps, inputProps } = useTextField({
    ...props,
    inputElementType: 'textarea'
  }, ref);

  return (
    <div style={{ display: 'flex', flexDirection: 'column', width: 200 }}>
      <label {...labelProps}>{label}</label>
      <textarea {...inputProps} ref={ref} />
    </div>
  );
}

<TextArea label="Description" />

import type {AriaTextFieldProps} from 'react-aria';
import {useTextField} from 'react-aria';

function TextArea(props: AriaTextFieldProps) {
  let { label } = props;
  let ref = React.useRef(null);
  let { labelProps, inputProps } = useTextField({
    ...props,
    inputElementType: 'textarea'
  }, ref);

  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        width: 200
      }}
    >
      <label {...labelProps}>{label}</label>
      <textarea {...inputProps} ref={ref} />
    </div>
  );
}

<TextArea label="Description" />

import type {AriaTextFieldProps} from 'react-aria';
import {useTextField} from 'react-aria';

function TextArea(
  props:
    AriaTextFieldProps
) {
  let { label } = props;
  let ref = React.useRef(
    null
  );
  let {
    labelProps,
    inputProps
  } = useTextField({
    ...props,
    inputElementType:
      'textarea'
  }, ref);

  return (
    <div
      style={{
        display: 'flex',
        flexDirection:
          'column',
        width: 200
      }}
    >
      <label
        {...labelProps}
      >
        {label}
      </label>
      <textarea
        {...inputProps}
        ref={ref}
      />
    </div>
  );
}

<TextArea label="Description" />

Usage#

The following examples show how to use the TextField component created in the above example.

Default value#

A TextField's value is empty by default, but an initial, uncontrolled, value can be provided using the defaultValue prop.

<TextField
  label="Email"
  defaultValue="me@email.com" />

<TextField
  label="Email"
  defaultValue="me@email.com" />

<TextField
  label="Email"
  defaultValue="me@email.com"
/>

Controlled value#

The value prop can be used to make the value controlled. The onChange event is fired when the user edits the text, and receives the new value.

function Example() {
  let [text, setText] = React.useState('');

  return (
    <>
      <TextField label="Your text" onChange={setText} />
      <p>Mirrored text: {text}</p>
    </>
  );
}

function Example() {
  let [text, setText] = React.useState('');

  return (
    <>
      <TextField label="Your text" onChange={setText} />
      <p>Mirrored text: {text}</p>
    </>
  );
}

function Example() {
  let [text, setText] =
    React.useState('');

  return (
    <>
      <TextField
        label="Your text"
        onChange={setText}
      />
      <p>
        Mirrored text:
        {' '}
        {text}
      </p>
    </>
  );
}

Description#

The description prop can be used to associate additional help text with a text field.

<TextField
  label="Email"
  description="Enter an email for us to contact you about your order."
/>

<TextField
  label="Email"
  description="Enter an email for us to contact you about your order."
/>

<TextField
  label="Email"
  description="Enter an email for us to contact you about your order."
/>

Error message#

The errorMessage prop can be used to help the user fix a validation error. It should be combined with the validationState prop to semantically mark the input element as invalid for assistive technologies.

<TextField
  label="Email"
  validationState="invalid"
  errorMessage="Please enter a valid email address." />

<TextField
  label="Email"
  validationState="invalid"
  errorMessage="Please enter a valid email address." />

<TextField
  label="Email"
  validationState="invalid"
  errorMessage="Please enter a valid email address."
/>

Disabled#

A TextField can be disabled using the isDisabled prop.

<TextField label="Email" isDisabled />

<TextField label="Email" isDisabled />

<TextField
  label="Email"
  isDisabled
/>

Read only#

The isReadOnly boolean prop makes the TextField's text content immutable. Unlike isDisabled, the TextField remains focusable and the contents can still be copied. See the MDN docs for more information.

<TextField label="Email" defaultValue="abc@adobe.com" isReadOnly />

<TextField
  label="Email"
  defaultValue="abc@adobe.com"
  isReadOnly
/>

<TextField
  label="Email"
  defaultValue="abc@adobe.com"
  isReadOnly
/>

Required#

A TextField can be marked as required using the isRequired prop. This is exposed to assistive technologies by React Aria. It's your responsibility to add additional visual styling if needed.

<TextField label="Email" isRequired />

<TextField label="Email" isRequired />

<TextField
  label="Email"
  isRequired
/>

HTML forms#

TextField supports the name prop for integration with HTML forms. In addition, attributes such as type, pattern, inputMode, and others are passed through to the underlying <input> element.

<TextField label="Email" name="email" type="email" />

<TextField label="Email" name="email" type="email" />

<TextField
  label="Email"
  name="email"
  type="email"
/>

Internationalization#

RTL#

In right-to-left languages, text fields should be mirrored. The label should be right aligned, along with the text in the text field. Ensure that your CSS accounts for this.

The intrinsic HTML element names that useTextField supports; e.g. input, textarea.

keyof Pick<IntrinsicHTMLElements, 'input' | 'textarea'>

A map of HTML element names and their interface types. For example 'a' -> HTMLAnchorElement.

'input'

Name	Type	Default	Description
`inputElementType`	`TextFieldIntrinsicElements`	`'input'`	The HTML element used to render the input, e.g. 'input', or 'textarea'. It determines whether certain HTML attributes will be included in `inputProps`. For example, `type`.
`aria-activedescendant`	`string`	—	Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application.
`aria-autocomplete`	`'none' \| 'inline' \| 'list' \| 'both'`	—	Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be presented if they are made.
`aria-haspopup`	`boolean \| 'false' \| 'true' \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog'`	—	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
`isDisabled`	`boolean`	—	Whether the input is disabled.
`isReadOnly`	`boolean`	—	Whether the input can be selected but not changed by the user.
`validationState`	`ValidationState`	—	Whether the input should display its "valid" or "invalid" visual styling.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission. Often paired with the `necessityIndicator` prop to add a visual indicator to the input.
`description`	`ReactNode`	—	A description for the field. Provides a hint such as specific requirements for what to choose.
`errorMessage`	`ReactNode`	—	An error message for the field.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`placeholder`	`string`	—	Temporary text that occupies the text input when it is empty.
`value`	`string`	—	The current value (controlled).
`defaultValue`	`string`	—	The default value (uncontrolled).
`onChange`	`( (value: TextFieldIntrinsicElements )) => void`	—	Handler that is called when the value changes.
`label`	`ReactNode`	—	The content to display as the label.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`excludeFromTabOrder`	`boolean`	—	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
`id`	`string`	—	The element's unique identifier. See MDN.
`autoComplete`	`string`	—	Describes the type of autocomplete functionality the input should provide if any. See MDN.
`maxLength`	`number`	—	The maximum number of characters supported by the input. See MDN.
`minLength`	`number`	—	The minimum number of characters required by the input. See MDN.
`name`	`string`	—	The name of the input element, used when submitting an HTML form. See MDN.
`pattern`	`string`	—	Regex pattern that the value of the input must match to be valid. See MDN.
`type`	`'text' \| 'search' \| 'url' \| 'tel' \| 'email' \| 'password' \| string & & {}`	—	The type of input to render. See MDN.
`inputMode`	`'none' \| 'text' \| 'tel' \| 'url' \| 'email' \| 'numeric' \| 'decimal' \| 'search'`	—	Hints at the type of data that might be entered by the user while editing the element or its contents. See MDN.
`onCopy`	`ClipboardEventHandler<HTMLInputElement>`	—	Handler that is called when the user copies text. See MDN.
`onCut`	`ClipboardEventHandler<HTMLInputElement>`	—	Handler that is called when the user cuts text. See MDN.
`onPaste`	`ClipboardEventHandler<HTMLInputElement>`	—	Handler that is called when the user pastes text. See MDN.
`onCompositionStart`	`CompositionEventHandler<HTMLInputElement>`	—	Handler that is called when a text composition system starts a new text composition session. See MDN.
`onCompositionEnd`	`CompositionEventHandler<HTMLInputElement>`	—	Handler that is called when a text composition system completes or cancels the current text composition session. See MDN.
`onCompositionUpdate`	`CompositionEventHandler<HTMLInputElement>`	—	Handler that is called when a new character is received in the current text composition session. See MDN.
`onSelect`	`ReactEventHandler<HTMLInputElement>`	—	Handler that is called when text in the input is selected. See MDN.
`onBeforeInput`	`FormEventHandler<HTMLInputElement>`	—	Handler that is called when the input value is about to be modified. See MDN.
`onInput`	`FormEventHandler<HTMLInputElement>`	—	Handler that is called when the input value is modified. See MDN.
`aria-errormessage`	`string`	—	Identifies the element that provides an error message for the object.

'valid' | 'invalid'

BaseEvent<ReactKeyboardEvent<any>>

SyntheticEvent & {stopPropagation: () => void,
continuePropagation: () => void
}

The type of ref object that can be passed to useTextField based on the given intrinsic HTML element name; e.g.RefObject<HTMLInputElement>, RefObject<HTMLTextAreaElement>.

RefObject<TextFieldHTMLElementType[T]>

The HTML element interfaces that useTextField supports based on what is defined for TextFieldIntrinsicElements; e.g. HTMLInputElement, HTMLTextAreaElement.

Pick<IntrinsicHTMLElements, TextFieldIntrinsicElements>

Name	Type	Description
`inputProps`	`TextFieldInputProps<TextFieldIntrinsicElements>`	Props for the input element.
`labelProps`	`DOMAttributes \| LabelHTMLAttributes<HTMLLabelElement>`	Props for the text field's visible label element, if any.
`descriptionProps`	`DOMAttributes`	Props for the text field's description element, if any.
`errorMessageProps`	`DOMAttributes`	Props for the text field's error message element, if any.

The type of inputProps returned by useTextField; e.g. InputHTMLAttributes, TextareaHTMLAttributes.

TextFieldHTMLAttributesType[TextFieldIntrinsicElements]

The HTML attributes interfaces that useTextField supports based on what is defined for TextFieldIntrinsicElements; e.g. InputHTMLAttributes, TextareaHTMLAttributes.

Pick<IntrinsicHTMLAttributes, TextFieldIntrinsicElements>

A map of HTML element names and their attribute interface types. For example 'a' -> AnchorHTMLAttributes<HTMLAnchorElement>.

All DOM attributes supported across both HTML and SVG elements.

Name	Type	Description
`id`	`string \| undefined`
`role`	`AriaRole \| undefined`
`tabIndex`	`number \| undefined`
`style`	`CSSProperties \| undefined`
`className`	`string \| undefined`