Skip to content

useField

Connects a custom control to the Field around it: its labels, description, error and state.

How was your stay?

Installation

  1. Add the registryOnce per project
  2. Add use-field

Usage

A Field links its label, description and error to the controls Base UI provides. A control of your own, such as a group of radio-like buttons or a canvas, connects to the field with these hooks. Date Picker, Tag Input and the other custom controls use them the same way.

useField reads the Field around the component. It returns the ids of the field's description and error, for aria-describedby, and whether the field is invalid or disabled. useFieldLabels returns the id of the field's FieldLabel, for aria-labelledby, so a plain <FieldLabel> with no htmlFor labels the radio group. Both hooks read the state that Base UI's Field keeps, so they stay current when a label, message or state changes later. Outside a Field, useField returns no describedBy and false for invalid and disabled.

A field labelled by a plain <label> rather than a FieldLabel has no label in that state. In that case, useFieldLabels reads labels from the DOM: the ones its labels option returns, such as a hidden input's labels, or else the labels of target itself, when target is an element that can have labels. It gives each label an id if it has none, and watches the field for labels that change later.

Base UI registers the description, error and label in effects, so the server render has no aria-describedby or aria-labelledby. It does have invalid and disabled.

The hidden FieldControl in the example submits the value with a form, takes part in the field's validation, and passes focus to the control when its label is clicked. Every FieldControl in a field takes the id that its label points at. When a field holds two custom controls, such as a date and a time, useFieldControlId gives the second one an id of its own.

API

useField

useField() takes no arguments. It reads the Field that the component renders in, and returns:

useFieldLabels

useFieldLabels(target, options?) takes the control, as a ref or the element itself, and these options. It reads the control's labels when the field has no FieldLabel.

It returns:

useFieldControlId

useFieldControlId(target, options?) takes the control's FieldControl, as a ref or the element itself, and these options.

It returns the id to give the FieldControl:

The file also exports FieldTarget, the type of target: a ref or an element.