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.

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

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: 'red', 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.