Field

A component that provides labeling and validation for form controls.

Name

Visible on your profile

import { Field } from 'base-ui-solid/field';
import styles from './index.module.css';

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

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

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

Anatomy

Import the component and assemble its parts:

Anatomy

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

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

API reference

Root

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

Prop

Type

Default

namestring—

Identifies the field when a form is submitted. Takes precedence over the name prop on the <Field.Control> component.string

actionsRefRefObject<Field.Root.Actions | null>—

A ref to imperative actions. validate: Validates the field when called.RefObject<Field.Root.Actions | null>

dirtyboolean—

Whether the field’s value has been changed from its initial value. Useful when the field state is controlled by an external library.boolean

touchedboolean—

Whether the field has been touched. Useful when the field state is controlled by an external library.boolean

disabledbooleanfalse

Whether the component should ignore user interaction. Takes precedence over the disabled prop on the <Field.Control> component.boolean

invalidboolean—

Whether the field is invalid. Useful when the field state is controlled by an external library.boolean

validatefunction—

A function for custom validation. Return a string or an array of strings with the error message(s) if the value is invalid. Returning nothing, null, an empty string, or an empty array means the value is valid. Asynchronous functions are supported, but they do not prevent form submission when using validationMode="onSubmit".

((value: unknown, formValues: Form.Values) => string | void | string[] | Promise<string | void | string[] | null> | null)

validationModeForm.ValidationMode'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.Form.ValidationMode

validationDebounceTimenumber0

How long to wait between validate callbacks if validationMode="onChange" is used. Specified in milliseconds.number

classfunction—

CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)

stylefunction—

Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)

renderfunction—

Replace the default element with a tag name, component, or render function.keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)

Data attributes

Name

Type

Default

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.

Root.State

type FieldRootState = {
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};

Root.Actions

type FieldRootActions = { validate: () => void };

Label

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

Prop

Type

Default

nativeLabelbooleantrue

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 (for example, <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.boolean

classfunction—

CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)

stylefunction—

Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)

renderfunction—

Replace the default element with a tag name, component, or render function.keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)

Data attributes

Name

Type

Default

data-disabled-—

Present when the field is disabled.-

data-valid-—

Present when the field is in a valid state.-

data-invalid-—

Present when the field is in an 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 a valid state.
`data-invalid`	Present when the field is in an 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.

Label.State

type FieldLabelState = {
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};

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](/solid/components/input), [Checkbox](/solid/components/checkbox), or [Select](/solid/components/select), among others, will work with Field out of the box.

Prop

Type

Default

defaultValueUnion—

-string | number | string[]

onValueChangefunction—

Callback fired when the value changes. Use when controlled.((value: string, eventDetails: Field.Control.ChangeEventDetails) => void)

classfunction—

CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)

stylefunction—

Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)

renderfunction—

Replace the default element with a tag name, component, or render function.keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)

Data attributes

Name

Type

Default

data-disabled-—

Present when the field is disabled.-

data-valid-—

Present when the field is in a valid state.-

data-invalid-—

Present when the field is in an 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 a valid state.
`data-invalid`	Present when the field is in an 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.State

type FieldControlState = {
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};

Control.ChangeEventReason

type FieldControlChangeEventReason = 'none';

Control.ChangeEventDetails

type FieldControlChangeEventDetails = {
  /** The reason for the event. */
  reason: 'none';
  /** The native event associated with the custom event. */
  event: Event;
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
};

Description

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

Prop

Type

Default

classfunction—

CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)

stylefunction—

Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)

renderfunction—

Replace the default element with a tag name, component, or render function.keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)

Data attributes

Name

Type

Default

data-disabled-—

Present when the field is disabled.-

data-valid-—

Present when the field is in a valid state.-

data-invalid-—

Present when the field is in an 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 a valid state.
`data-invalid`	Present when the field is in an 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.State

type FieldDescriptionState = {
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};

Item

Groups individual items in a checkbox group or radio group with a label and description. Renders a <div> element.

Prop

Type

Default

disabledbooleanfalse

Whether the wrapped control should ignore user interaction. The disabled prop on <Field.Root> takes precedence over this.boolean

classfunction—

CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)

stylefunction—

Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)

renderfunction—

Replace the default element with a tag name, component, or render function.keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)

Data attributes

Name

Type

Default

data-disabled-—

Present when the field is disabled.-

data-valid-—

Present when the field is in a valid state.-

data-invalid-—

Present when the field is in an 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 a valid state.
`data-invalid`	Present when the field is in an 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.

Item.State

type FieldItemState = {
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};

Error

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

Prop

Type

Default

matchUnion—

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.

boolean | 'valid' | 'badInput' | 'customError' | 'patternMismatch' | 'rangeOverflow' | 'rangeUnderflow' | 'stepMismatch' | 'tooLong' | 'tooShort' | 'typeMismatch' | 'valueMissing'

classfunction—

CSS class applied to the element, or a function that returns a class based on the component’s state.JSX.ClassValue | ((state) => JSX.ClassValue)

stylefunction—

Style applied to the element, or a function that returns a style object based on the component’s state.JSX.CSSProperties | string | ((state) => JSX.CSSProperties | string | undefined)

renderfunction—

Replace the default element with a tag name, component, or render function.keyof JSX.IntrinsicElements | Component | ((props, state) => JSX.Element)

Data attributes

Name

Type

Default

data-disabled-—

Present when the field is disabled.-

data-valid-—

Present when the field is in a valid state.-

data-invalid-—

Present when the field is in an 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.-

data-starting-style-—

Present when the error message begins animating in.-

data-ending-style-—

Present when the error message is animating out.-

Attribute	Description	-
`data-disabled`	Present when the field is disabled.
`data-valid`	Present when the field is in a valid state.
`data-invalid`	Present when the field is in an 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.
`data-starting-style`	Present when the error message begins animating in.
`data-ending-style`	Present when the error message is animating out.

Error.State

type FieldErrorState = {
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};

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\*function—

A function that accepts the field validity state as an argument.((state: Field.Validity.State) => JSX.Element)

Validity.State

type FieldValidityState = {
  /** The validity state. */
  validity: {
    badInput: boolean;
    customError: boolean;
    patternMismatch: boolean;
    rangeOverflow: boolean;
    rangeUnderflow: boolean;
    stepMismatch: boolean;
    tooLong: boolean;
    tooShort: boolean;
    typeMismatch: boolean;
    valueMissing: boolean;
    valid: boolean | null;
  };
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  errors: string[];
  value: unknown;
  error: string;
  initialValue: unknown;
};