Field

A high-quality, unstyled React field component that provides labeling and validation for form controls.

A component that provides labeling and validation for form controls.

Name

Visible on your profile

Anatomy

Import the component and assemble its parts:

Anatomy

import { Field } from '@base-ui/react/field';

<Field.Root>
  <Field.Label />
  <Field.Control />
  <Field.Description />
  <Field.Item />
  <Field.Error />
  <Field.Validity />
</Field.Root>;

API reference

Root

Name	Type	Default	Description
`disabled`Optional	`boolean \| undefined`	`false`	Whether the component should ignore user interaction. Takes precedence over the `disabled` prop on the `<Field.Control>` component.
`name`Optional	`string \| undefined`	—	Identifies the field when a form is submitted. Takes precedence over the `name` prop on the `<Field.Control>` component.
`value`Required	`unknown,`	—	—
`formValues`Required	`Form.Values,`	—	—
`validationMode`Optional	`Form.ValidationMode \| undefined`	`onSubmit`	Determines when the field should be validated. This takes precedence over the `validationMode` prop on `<Form>`. - `onSubmit`: triggers validation when the form is submitted, and re-validates on change after submission. - `onBlur`: triggers validation when the control loses focus. - `onChange`: triggers validation on every change to the control value.
`validationDebounceTime`Optional	`number \| undefined`	`0`	How long to wait between `validate` callbacks if `validationMode="onChange"` is used. Specified in milliseconds.
`invalid`Optional	`boolean \| undefined`	—	Whether the field is invalid. Useful when the field state is controlled by an external library.
`dirty`Optional	`boolean \| undefined`	—	Whether the field's value has been changed from its initial value. Useful when the field state is controlled by an external library.
`touched`Optional	`boolean \| undefined`	—	Whether the field has been touched. Useful when the field state is controlled by an external library.
`actionsRef`Optional	`React.RefObject<FieldRoot.Actions \| null> \| undefined`	—	A ref to imperative actions. - `validate`: Validates the field when called.

Label

Name	Type	Default	Description
`nativeLabel`Optional	`boolean \| undefined`	`true`	Whether the component renders a native `<label>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a label (e.g. `<div>`). This is useful to avoid inheriting label behaviors on `<button>` controls (such as `<Select.Trigger>` and `<Combobox.Trigger>`), including avoiding `:hover` on the button when hovering the label, and preventing clicks on the label from firing on the button.

Control

Name	Type	Default	Description
`defaultValue`Optional	`React.ComponentProps<'input'>['defaultValue'] \| undefined`	—	—

Item

Name	Type	Default	Description
`disabled`Optional	`boolean \| undefined`	`false`	Whether the wrapped control should ignore user interaction. The `disabled` prop on `<Field.Root>` takes precedence over this.

Error

Name	Type	Default	Description
`match`Optional	`boolean \| keyof ValidityState \| undefined`	—	Determines whether to show the error message according to the field's [ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState). Specifying `true` will always show the error message, and lets external libraries control the visibility.

Field

Anatomy

API reference

Root

Label

Control

Item

Error

On this page