Field
Form field with automatic label association, validation, and error display
Wraps a single form control to give it an associated label, a description, and validation messages, all wired together for accessibility automatically. Reach for it around any input, select, checkbox, switch, or radio group that needs a label or error display. To group several fields under one legend, use Fieldset; to wrap and submit the whole form, use Form.
Preview
Installation
Usage
Composition
Examples
With Description
Display helper text below the control.
We'll never share your email with anyone else.
Constraint Validation
Use native HTML validation attributes (required, pattern, minLength, type, etc.) with a single FieldError that displays the browser's native error message.
Per-State Messages
Customize messages for specific validity states by pairing multiple FieldError components with different match props. Useful for i18n or overriding the browser's default messages.
For other ways to customize messages, see Custom Validation (via a validate function) and server-side errors via the Form component's errors prop.
Custom Validation
Run custom validation logic with the validate prop. Supports async functions and debouncing.
With Select
Wrap a Select component with Field for labeling and validation.
With Checkbox
Use implicit labeling by placing a Checkbox inside FieldLabel.
With Switch
Use implicit labeling by placing a Switch inside FieldLabel.
Receive email notifications when someone mentions you.
With Radio Group
Compose Field with Fieldset and RadioGroup using FieldItem for each option.
With Checkbox Group
Compose Field with Fieldset and CheckboxGroup using FieldItem for each option.
With Slider
Wrap a Slider component with Field. Use SliderLabel (not FieldLabel) since Slider is a trigger-based control.
Adjust the output volume level.
Disabled
Disable the entire field, cascading to all child components.
Contact an administrator to change your username.
Animating Error Visibility
Wrap FieldError in FieldErrorSlot to smoothly animate the error's height and opacity on mount/unmount. When empty, the slot collapses to zero space, so there is no extra gap in the layout when no error is present.
The height animation relies on CSS interpolate-size: allow-keywords, which at the time of writing is only supported in Chromium 129+ (Chrome, Edge, Arc, Brave). Safari and Firefox do not yet support it, so on those browsers the error appears/disappears instantly (opacity still cross-fades). The component still works; only the height tween is degraded.
Keep the slot in normal block flow. interpolate-size animates the slot's height from 0 to auto, but flex and grid items have an automatic min-height: auto that clamps them to their content's height, so the moment the error mounts the slot jumps straight to full height instead of animating. Don't put display: flex/grid on the Field; if you need to center or lay out the field's contents, wrap the inner controls (e.g. an OTP field) in their own flex container. If the slot genuinely must be a flex/grid item, give it min-h-0 (min-height: 0) to remove the clamp.
API Reference
The Field component is built on top of Base UI's Field. All Base UI props are supported.
For the complete Base UI API, see the Base UI Field documentation.
Props
Field
Groups all parts of the field. Renders a <div> element.
FieldLabel
An accessible label automatically associated with the field control. Renders a <label> element. Use for input-type controls (Input, NumberField, OTPField, Autocomplete, Combobox) and toggle controls (Checkbox, Radio, Switch). For trigger-based controls like Select, use SelectLabel instead.
FieldControl
The form control to label and validate. Renders an <input> element. You can omit this and use any Base UI input component directly inside Field instead.
FieldControl inherits its visual styling from the Input component (inputVariants). Changes to Input's variant styles propagate to every FieldControl, so keep that in mind when customizing either.
FieldDescription
A paragraph with additional information about the field. Renders a <p> element.
FieldError
An error message displayed when the field fails validation. Renders a <div> element.
FieldErrorSlot
Optional wrapper for FieldError that animates the error's height (via interpolate-size) and opacity on mount/unmount. When empty, uses a negative top margin to collapse to zero space, so there's no layout difference versus not using a slot at all. When switching between multiple match-specific FieldError components, the switch is instant (no cross-fade). Renders a <div> element.
Assumes the parent Field uses the default space-y-2 spacing. If you customize the Field's spacing, override the slot's margin classes to match. Keep the slot in block flow: flex/grid items have an automatic min-height: auto that clamps the slot to its content height and breaks the interpolate-size height tween (the error jumps instead of animating). Don't put display: flex/grid on the Field; if the slot must be a flex/grid item, add min-h-0 to it.
FieldItem
Groups individual items in a checkbox group or radio group with a label and description. Renders a <div> element.
FieldValidity
Render prop component for custom validity display. Does not render any DOM element.