Stable in React

Field

Labels and validates a form control.

Loading React 19.3.1…

Hover a part or use it. The code follows. · Loading React…

502Tests passing in React · 0 failing

11.0 KiBSize

Not measured yetMemory

Not measured yetSpeed

productdevbook and 16 upstream authors22 commits · last Nov 4

Install#

One package per framework. Field's parts come from it; the anatomy tab at the top shows how they nest.

bun add @▢▢▢▢/react

7 parts. The example uses five of them; the data does not say which are required.

Field.RootGroups all parts of the field.
Field.LabelAn accessible label that is automatically associated with the field control.
Field.ControlThe form control to label and validate.
Field.DescriptionA paragraph with additional information about the field.
Field.ErrorAn error message displayed if the field control fails validation.
Field.ItemGroups individual items in a checkbox group or radio group with a label and description. Not in the example.
Field.ValidityUsed to display a custom message based on the field's validity. Not in the example.

Examples#

The demo at the top is the one example this component has so far.

Styling and accessibility#

The parts ship no styles. Style their states with these attributes; the CSS tab at the top has a sheet. The same CSS works in all five frameworks.

[data-disabled]Present when the field is disabled. On Root, Label, Control, Description, Error, Item.
[data-touched]Present when the field has been touched. On Root, Label, Control, Description, Error, Item.
[data-dirty]Present when the field's value has changed. On Root, Label, Control, Description, Error, Item.
[data-valid]Present when the field is valid. On Root, Label, Control, Description, Error, Item.
[data-invalid]Present when the field is invalid. On Root, Label, Control, Description, Error, Item.
[data-filled]Present when the field is filled. On Root, Label, Control, Description, Error, Item.
[data-focused]Present when the field control is focused. On Root, Label, Control, Description, Error, Item.
[data-starting-style]Present when the error message begins animating in. On Error.
[data-ending-style]Present when the error message is animating out. On Error.

Keyboard

Field adds no keys; the control inside keeps its own. Pressing Enter in a form still submits it, and the field validates first.

Set for you

a <label> tied to the control, or aria-labelledby on the control when nativeLabel is offthe control is read with its name, and clicking the label focuses itLabel
aria-describedby to Description and Errorthe hint and the error are read with the controlControl
aria-invalid="true" when validation failsa screen reader says the value is not acceptedControl
renders only while there is an error to showan empty error is never announcedError
groups one checkbox or radio with its own label and descriptioneach option in a group is named on its ownItem

API reference#

15 props across 7 parts, in React syntax, and className, style, render once for every part. Open a row to try it.

Filter props

Field · all parts

Shared propsEvery part that renders an element takes these.

classNameCSS class applied to the element, or a function that returns a class based on the component's state.string | ((state: State) => string | undefined)

styleStyle applied to the element, or a function that returns a style object based on the component's state.React.CSSProperties | ((state: State) => React.CSSProperties | undefined)

renderAllows you to replace the component's HTML element with a different tag, or compose it with another component.React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, State>

Use it in React#

What differs from the React API. Switch the framework at the top of the page.

@▢▢▢▢/react is the React 19 package. Its parts, props, data attributes and error messages are upstream Base UI's, and upstream's own tests run against it.

Parts
Each component is its own entry point and exports one namespace named after it.
```
import { Switch } from '@base-ui-next/react/switch'

export function Example() {
  return (
    <Switch.Root>
      <Switch.Thumb />
    </Switch.Root>
  )
}
```
A part renders the element its API reference names, such as a <span> for Switch.Root.
Props and events
Props and callbacks have upstream's names and signatures: onCheckedChange(checked, details), onOpenChange(open, details), onValueChange(value, details). details carries reason, event, cancel() and allowPropagation(). Native handlers are React's (onClick, onKeyDown), and event.preventBaseUIHandler() stops a part's own handler.
Styling
className takes a string or a function (state) => string; style takes an object or a function (state) => object. The state's data-* attributes are on the element for CSS.
render
render takes an element (render={<a href="/docs" />}) or a function (props, state) => element that spreads props on what it returns.
Refs
ref reaches the part's element. Imperative handles are ref props, as upstream: inputRef, and actionsRef ({ validate } on Field and Form, { unmount, close } on Dialog).
Binding
A part is controlled when its value prop (checked, open, value) is set, and uncontrolled with the default form (defaultChecked, defaultOpen, defaultValue). React has no two-way binding: pair the value with its change callback.
From @base-ui/react
Change the import from @base-ui/react/<component> to @▢▢▢▢/react/<component>.
From @base-ui/react
Nothing else changes: props, parts, data attributes and errors are the same.