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';

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
`validate`	`(value: T) => ValidationError \| true \| null \| undefined`	Default: —
A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.
`validationBehavior`	`'aria' \| 'native'`	Default: `'aria'`
Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
`isInvalid`	`boolean`	Default: —
Whether the input value is invalid.
`errorMessage`	`ReactNode \| (v: ValidationResult) => ReactNode`	Default: —
An error message for the field.
`description`	`ReactNode`	Default: —
A description for the field. Provides a hint such as specific requirements for what to choose.
`aria-details`	`string`	Default: —
Identifies the element (or elements) that provide a detailed, extended description for the object.
`aria-describedby`	`string`	Default: —
Identifies the element (or elements) that describes the object.
`aria-labelledby`	`string`	Default: —
Identifies the element (or elements) that labels the current element.
`aria-label`	`string`	Default: —
Defines a string value that labels the current element.
`id`	`string`	Default: —
The element's unique identifier. See MDN.
`label`	`ReactNode`	Default: —
The content to display as the label.
`labelElementType`	`ElementType`	Default: `'label'`
The HTML element used to render the label, e.g. 'label', or 'span'.

FieldAria

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