useField

Provides the accessibility implementation for input fields. Fields accept user input, gain context from their label, and may display a description or error message.

Introduction

The useField hook associates a form control with a label, and an optional description and/or error message. This is useful for providing context about how users should fill in a field, or a validation message. useField takes care of creating ids for each element and associating them with the correct ARIA attributes (aria-labelledby and aria-describedby).

By default, useField assumes that the label is a native HTML <label> element. However, if you are labeling a non-native form element, be sure to use an element other than a <label> and set the labelElementType prop appropriately.

Note: Many other React Aria hooks such as useTextField, useSelect, and useComboBox already include support for description and error message elements. If you're using one of those hooks, there's no need to use useField.

Example

Preferred contact method

Select the best way to contact you about issues with your account.

Preferred contact method

Select a contact method.

import {useField} from 'react-aria/useField';

function ContactPicker(props) {
  let {labelProps, fieldProps, descriptionProps, errorMessageProps} = useField(props);

  return (
    <div style={{display: 'flex', flexDirection: 'column', width: 200, marginBottom: 20}}>
      <label {...labelProps}>{props.label}</label>
      <select {...fieldProps}>
        <option>Email</option>
        <option>Phone</option>
        <option>Fax</option>
        <option>Carrier pigeon</option>
      </select>
      {props.description &&
        <div {...descriptionProps} style={{fontSize: 12}}>{props.description}</div>
      }
      {props.errorMessage &&
        <div {...errorMessageProps} style={{color: '#b00020', fontSize: 12}}>{props.errorMessage}</div>
      }
    </div>
  );
}

<>
  <ContactPicker
    label="Preferred contact method"
    description="Select the best way to contact you about issues with your account." />
  <ContactPicker
    label="Preferred contact method"
    errorMessage="Select a contact method." />
</>

API

useField(props: AriaFieldProps): FieldAria

AriaFieldProps

Name	Type	Default
`labelElementType`	`ElementType`	Default: `'label'`
The HTML element used to render the label, e.g. 'label', or 'span'.

FieldAria

Name	Type
`descriptionProps`	`DOMAttributes`
Props for the description element, if any.
`errorMessageProps`	`DOMAttributes`
Props for the error message element, if any.
`labelProps`	`DOMAttributes \| LabelHTMLAttributes<HTMLLabelElement>`
Props to apply to the label container element.
`fieldProps`	`AriaLabelingProps & DOMProps`
Props to apply to the field container element being labeled.