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>
  );
}

Anatomy

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>

API reference

Root

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

name

string

Name: name
Description: Identifies the field when a form is submitted. Takes precedence over the name prop on the <Field.Control> component.
Type: string | undefined

disabled

boolean

(default:

false

)

Name: disabled
Description: Whether the component should ignore user interaction. Takes precedence over the disabled prop on the <Field.Control> component.
Type: boolean | undefined
Default: false

invalid

boolean

Name: invalid
Description: Whether the field is forcefully marked as invalid.
Type: boolean | undefined

validate

Union

Name: validate
Description: A function for custom validation. Return a string or an array of strings with the error message(s) if the value is invalid, or null if the value is valid.
Type: | (( value: unknown, formValues: Record<string, unknown>, ) => | string | string[] | Promise<string | string[] | null> | null) | undefined

validationMode

'onBlur' | 'onChange'

(default:

'onBlur'

)

Name: validationMode
Description: Determines when the field should be validated.

onBlur triggers validation when the control loses focus

onChange triggers validation on every change to the control value
Type: 'onBlur' | 'onChange' | undefined
Default: 'onBlur'

validationDebounceTime

number

(default:

0

)

Name: validationDebounceTime
Description: How long to wait between validate callbacks if validationMode="onChange" is used. Specified in milliseconds.
Type: number | undefined
Default: 0

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Field.Root.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Field.Root.State, ) => ReactElement)

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.

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.

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Field.Root.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Field.Root.State, ) => ReactElement)

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.

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.

defaultValue

Union

Name: defaultValue
Type: string | number | string[] | undefined

onValueChange

function

Name: onValueChange
Description: Callback fired when the value changes. Use when controlled.
Type: | (( value: string, eventDetails: Field.Control.ChangeEventDetails, ) => void) | undefined

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Field.Root.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Field.Root.State, ) => ReactElement)

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.

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.

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Field.Root.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Field.Root.State, ) => ReactElement)

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.

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.

match

Union

Name: match
Description: Determines whether to show the error message according to the field’s ValidityState. Specifying true will always show the error message, and lets external libraries control the visibility.
Type: | boolean | 'valid' | 'badInput' | 'customError' | 'patternMismatch' | 'rangeOverflow' | 'rangeUnderflow' | 'stepMismatch' | 'tooLong' | 'tooShort' | 'typeMismatch' | 'valueMissing' | undefined

className

string | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Field.Root.State) => string)

render

ReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Field.Root.State, ) => ReactElement)

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.

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.

children^*

((state: FieldValidityState) => ReactNode)

Name: children
Description: A function that accepts the field validity state as an argument.

<Field.Validity> {(validity) => { return <div>...</div> }} </Field.Validity>
Type: (state: FieldValidityState) => ReactNode