Skip to contents
1.3.0GitHub

Forms

A guide to building forms with Base UI components.

View as Markdown

Base UI form control components extend the native constraint validation API so you can build forms for collecting user input or providing control over an interface. They also integrate seamlessly with third-party libraries like React Hook Form and TanStack Form.

Must be 3 or more characters long

Enter a registry URL with optional tags

Server type
Scaling threshold
20% – 80%
Storage type
Allowed network protocols

Naming form controls

Form controls must have an accessible name in order to be recognized by assistive technologies. Use the label strategy below for each control type.

Input controls

Use <Field.Label> or a native <label> to label the following controls:

  • Input
  • NumberField
  • Autocomplete
  • Combobox (input outside popup)
  • Checkbox
  • Radio
  • Switch

You can implicitly label <Checkbox>, <Radio> and <Switch> components by enclosing them with <Field.Label>:

Implicitly labeling a switch

Trigger-based controls

  • Combobox (input inside popup): use <Combobox.Label>.
  • Select: use <Select.Label>.
  • Slider: use <Slider.Label>. For multi-thumb sliders, also add an aria-label on each <Slider.Thumb> to distinguish the thumbs.

Fallback

If no visible label is rendered, provide aria-label on the actual form control.

Describing the control

<Field.Description> automatically assigns an accessible description:

Labeling select and slider

Labeling control groups

Compose <Fieldset> when a single label applies to multiple controls, such as a range slider with multiple thumbs or a section that combines several inputs. For checkbox and radio groups, keep the group label in <Fieldset.Legend> and wrap each option with <Field.Item>:

Composing range slider and radio group with fieldset

<Field.Item> should enclose each checkbox or radio option so every control has its own label and description:

Explicitly labeling checkboxes in a checkbox group

Building form fields

Pass the name prop to <Field.Root> to include the wrapped control’s value when a parent form is submitted:

Assigning field name to combobox

Submitting data

You can take over form submission using the native onSubmit, or custom onFormSubmit props:

Native submission using onSubmit

When using onFormSubmit, you receive form values as a JavaScript object, with eventDetails provided as a second argument. Additionally, preventDefault() is automatically called on the native submit event:

Submission using onFormSubmit

Constraint validation

Base UI form components support native HTML validation attributes for many validation rules:

  • required specifies a required field.
  • minLength and maxLength specify a valid length for text fields.
  • pattern specifies a regular expression that the field value must match.
  • step specifies an increment that numeric field values must be an integral multiple of.
Defining constraint validation on a text field

Base UI form components use a hidden input to participate in native form submission and validation. To anchor the hidden input near a control so the native validation bubble points to the correct area, ensure the component has been given a name, and wrap controls in a relatively positioned container for best results.

Positioning hidden inputs

Custom validation

You can add custom validation logic by passing a synchronous or asynchronous validation function to the validate prop, which runs after native validations have passed.

Use the validationMode prop to configure when validation is performed:

  • onSubmit (default) validates all fields when the containing <Form> is submitted, afterwards invalid fields revalidate when their value changes.
  • onBlur validates the field when focus moves away.
  • onChange validates the field when the value changes, for example, after each keypress in a text field or when a checkbox is checked or unchecked.

validationDebounceTime can be used to debounce the function in use cases such as asynchronous requests or text fields that validate onChange.

Text input using custom asynchronous validation

Server-side validation

You can pass errors returned by (post-submission) server-side validation to the errors prop, which will be merged into the client-side field state for display.

This should be an object with field names as keys, and an error string or array of strings as the value. Once a field’s value changes, any corresponding error in errors will be cleared from the field state.

Displaying errors returned by server-side validation

When using Server Functions with Form Actions you can return server-side errors from useActionState to the errors prop. A demo is available here.

Returning errors from useActionState

Displaying errors

Use <Field.Error> without children to automatically display the field’s native error message when invalid. The match prop can be used to customize the message based on the validity state, and manage internationalization from your application logic:

Customizing error message for a required field

React Hook Form

React Hook Form is a popular library that you can integrate with Base UI to externally manage form and field state for your existing components.

Must be 3 or more characters long

Enter a registry URL with optional tags

Server type
Scaling threshold
20% – 80%
Storage type
Allowed network protocols

Initialize the form

Initialize the form with the useForm hook, assigning the initial value of each field by their name in the defaultValues parameter:

Initialize a form instance

Integrate components

Use the <Controller> component to integrate with any <Field> component, forwarding the name, field, and fieldState render props to the appropriate part:

Integrating the controller component with Base UI field

For React Hook Form to focus invalid fields when performing validation, you must ensure that any wrapping components forward the ref to the underlying Base UI component. You can typically accomplish this using the inputRef prop, or directly as the ref for components that render an input element like <NumberField.Input>.

Field validation

Specify rules on the <Controller> in the same format as register options, and use the match prop to delegate control of the error rendering:

Defining validation rules and displaying errors

Submitting data

Wrap your submit handler function with handleSubmit to receive the form values as a JavaScript object for further handling:

Form submission handler

TanStack Form

TanStack Form is a form library with a function-based API for orchestrating validations that can also be integrated with Base UI.

Must be 3 or more characters long

Enter a registry URL with optional tags

Server type
Scaling threshold
20% – 80%
Storage type
Allowed network protocols

Initialize the form

Create a form instance with the useForm hook, assigning the initial value of each field by their name in the defaultValues parameter:

Initialize a form instance

Integrate components

Use the <form.Field> component from the form instance to integrate with Base UI components using the children prop, forwarding the various field render props to the appropriate part:

Integrating TanStack Form with Base UI components

The Base UI <Form> component is not needed when using TanStack Form.

Form validation

To configure a native <form>-like validation strategy:

  1. Use the additional revalidateLogic hook and pass it to useForm.
  2. Pass a validation function to the validators.onDynamic prop on <form.Field> that returns an error object with keys corresponding to the field names.

This validates all fields when the first submission is attempted, and revalidates any invalid fields when their values change again.

Form-level validators

Field validation

You can pass additional validator functions to individual <form.Field> components to add validations on top of the form-level validators:

Field-level validators

Submitting data

To submit the form:

  1. Pass a submit handler function to the onSubmit parameter of useForm.
  2. Call form.handleSubmit() from an event handler such as form onSubmit or onClick on a button.
Form submission handler