useLabel

Provides the accessibility implementation for labels and their associated elements. Labels provide context for user inputs.

Example

The useLabel hook associates a label with a field. It automatically handles creating an id for the field and associates the label with it.

Favorite color

import {useLabel} from '@react-aria/label';

function ColorField(props) {
  let {labelProps, fieldProps} = useLabel(props);

  return (
    <>
      <label {...labelProps}>{props.label}</label>
      <select {...fieldProps}>
        <option>Indigo</option>
        <option>Maroon</option>
        <option>Chartreuse</option>
      </select>
    </>
  );
}

<ColorField label="Favorite color" />

By default, useLabel 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.

API

useLabel(props: LabelAriaProps): LabelAria

LabelAriaProps

Name	Type	Default
`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'.

LabelAria

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.