Field

A component that provides labelling and validation for form controls.

Name

Visible on your profile

import * as React from 'react';
import { Field } from '@base-ui-components/react/field';
import styles from './index.module.css';

export default function ExampleField() {
  return (
    <Field.Root className={styles.Field}>
      <Field.Label className={styles.Label}>Name</Field.Label>
      <Field.Control required placeholder="Required" className={styles.Input} />

      <Field.Error className={styles.Error} match="valueMissing">
        Please enter your name
      </Field.Error>

      <Field.Description className={styles.Description}>
        Visible on your profile
      </Field.Description>
    </Field.Root>
  );
}

API reference

Import the component and assemble its parts:

Anatomy

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

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

Root

Groups all parts of the field. Renders a <div> element.

Prop	Type	Default
`name`	`string`	`undefined`
`disabled`	`boolean`	`false`
`invalid`	`boolean`	`undefined`
`validate`	`(value) => string \| string[] \| null \| Promise`	`undefined`
`validationMode`	`'onBlur' \| 'onChange'`	`'onBlur'`
`validationDebounceTime`	`number`	`0`
`className`	`string \| (state) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Attribute	Description
`data-disabled`	Present when the field is disabled.
`data-valid`	Present when the field is valid.
`data-invalid`	Present when the field is invalid.
`data-dirty`	Present when the field's value has changed.
`data-touched`	Present when the field has been touched.
`data-filled`	Present when the field is filled.
`data-focused`	Present when the field control is focused.

Label

An accessible label that is automatically associated with the field control. Renders a <label> element.

Prop	Type	Default
`className`	`string \| (state) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Attribute	Description
`data-disabled`	Present when the field is disabled.
`data-valid`	Present when the field is in valid state.
`data-invalid`	Present when the field is in invalid state.
`data-dirty`	Present when the field's value has changed.
`data-touched`	Present when the field has been touched.
`data-filled`	Present when the field is filled.
`data-focused`	Present when the field control is focused.

Control

The form control to label and validate. Renders an <input> element.

You can omit this part and use any Base UI input component instead. For example, Input, Checkbox, or Select, among others, will work with Field out of the box.

Prop	Type	Default
`onValueChange`	`(value, event) => void`	`undefined`
`className`	`string \| (state) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Attribute	Description
`data-disabled`	Present when the field is disabled.
`data-valid`	Present when the field is in valid state.
`data-invalid`	Present when the field is in invalid state.
`data-dirty`	Present when the field's value has changed.
`data-touched`	Present when the field has been touched.
`data-filled`	Present when the field is filled.
`data-focused`	Present when the field control is focused.

Description

A paragraph with additional information about the field. Renders a <p> element.

Prop	Type	Default
`className`	`string \| (state) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Attribute	Description
`data-disabled`	Present when the field is disabled.
`data-valid`	Present when the field is in valid state.
`data-invalid`	Present when the field is in invalid state.
`data-dirty`	Present when the field's value has changed.
`data-touched`	Present when the field has been touched.
`data-filled`	Present when the field is filled.
`data-focused`	Present when the field control is focused.

Error

An error message displayed if the field control fails validation. Renders a <div> element.

Prop	Type	Default
`match`	`\| 'badInput' \| 'customError' \| 'patternMismatch' \| 'rangeOverflow' \| 'rangeUnderflow' \| 'stepMismatch' \| 'tooLong' \| 'tooShort' \| 'typeMismatch' \| 'valid' \| 'valueMissing'`	`undefined`
`forceShow`	`boolean`	`undefined`
`className`	`string \| (state) => string`	`undefined`
`render`	`\| React.ReactElement \| (props, state) => React.ReactElement`	`undefined`

Attribute	Description
`data-disabled`	Present when the field is disabled.
`data-valid`	Present when the field is in valid state.
`data-invalid`	Present when the field is in invalid state.
`data-dirty`	Present when the field's value has changed.
`data-touched`	Present when the field has been touched.
`data-filled`	Present when the field is filled.
`data-focused`	Present when the field control is focused.

Validity

Used to display a custom message based on the field’s validity. Requires children to be a function that accepts field validity state as an argument.

Prop	Type	Default
`children`	`(validity) => React.ReactNode`	`undefined`