useTextField

Provides the behavior and accessibility implementation for a text field.

API#

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

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 returns two sets of props that you should spread onto the appropriate element:

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#

function TextField(props) {
  let {label} = props;
  let ref = React.useRef();
  let {labelProps, inputProps} = useTextField(props, ref);

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

<TextField label="Email" placeholder="abc@example.com" />

function TextField(props) {
  let {label} = props;
  let ref = React.useRef();
  let {labelProps, inputProps} = useTextField(props, ref);

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

<TextField label="Email" placeholder="abc@example.com" />

function TextField(
  props
) {
  let {label} = props;
  let ref = React.useRef();
  let {
    labelProps,
    inputProps
  } = useTextField(
    props,
    ref
  );

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

<TextField
  label="Email"
  placeholder="abc@example.com"
/>

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.