docs/handbook/forms

Forms

A guide to building forms with Base UI components.

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.

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
OTPField
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

import { Field } from "@logic-ui/react/field";
import { Switch } from "@logic-ui/react/switch";

<Field.Root>
  <Field.Label>
    <Switch.Root />
    Developer mode
  </Field.Label>
  <Field.Description>Enables extra tools for web developers</Field.Description>
</Field.Root>;

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

import { Form } from "@logic-ui/react/form";
import { Field } from "@logic-ui/react/field";
import { Select } from "@logic-ui/react/select";
import { Slider } from "@logic-ui/react/slider";

<Form>
  <Field.Root>
    <Select.Root>
      <Select.Label>Time zone</Select.Label>
      <Select.Trigger />
    </Select.Root>
    <Field.Description>Used for notifications and reminders</Field.Description>
  </Field.Root>

  <Field.Root>
    <Slider.Root defaultValue={50}>
      <Slider.Label>Zoom level</Slider.Label>
      <Field.Description>
        Adjust the size of the user interface
      </Field.Description>
      <Slider.Control>
        <Slider.Track>
          <Slider.Thumb />
        </Slider.Track>
      </Slider.Control>
    </Slider.Root>
  </Field.Root>
</Form>;

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

import { Form } from "@logic-ui/react/form";
import { Field } from "@logic-ui/react/field";
import { Fieldset } from "@logic-ui/react/fieldset";
import { Radio } from "@logic-ui/react/radio";
import { RadioGroup } from "@logic-ui/react/radio-group";
import { Slider } from "@logic-ui/react/slider";

<Form>
  <Field.Root>
    {/* @highlight-start */}
    <Fieldset.Root render={<Slider.Root />}>
      <Fieldset.Legend>Price range</Fieldset.Legend>
      {/* @highlight-end */}
      <Slider.Control>
        <Slider.Track>
          <Slider.Thumb aria-label="Minimum price" />
          <Slider.Thumb aria-label="Maximum price" />
        </Slider.Track>
      </Slider.Control>
      {/* @highlight */}
    </Fieldset.Root>
  </Field.Root>

  <Field.Root>
    {/* @highlight-start */}
    <Fieldset.Root render={<RadioGroup />}>
      <Fieldset.Legend>Storage type</Fieldset.Legend>
      {/* @highlight-end */}
      <Radio.Root value="ssd" />
      <Radio.Root value="hdd" />
      {/* @highlight */}
    </Fieldset.Root>
  </Field.Root>
</Form>;

<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

import { Form } from "@logic-ui/react/form";
import { Field } from "@logic-ui/react/field";
import { Fieldset } from "@logic-ui/react/fieldset";
import { Checkbox } from "@logic-ui/react/checkbox";
import { CheckboxGroup } from "@logic-ui/react/checkbox-group";

<Field.Root>
  <Fieldset.Root render={<CheckboxGroup />}>
    <Fieldset.Legend>Backup schedule</Fieldset.Legend>
    {/* @highlight */}
    <Field.Item>
      <Checkbox.Root value="daily" />
      <Field.Label>Daily</Field.Label>
      <Field.Description>Daily at 00:00</Field.Description>
      {/* @highlight-start */}
    </Field.Item>
    <Field.Item>
      {/* @highlight-end */}
      <Checkbox.Root value="monthly" />
      <Field.Label>Monthly</Field.Label>
      <Field.Description>On the 5th of every month at 23:59</Field.Description>
      {/* @highlight */}
    </Field.Item>
  </Fieldset.Root>
</Field.Root>;

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

import { Form } from "@logic-ui/react/form";
import { Field } from "@logic-ui/react/field";
import { Combobox } from "@logic-ui/react/combobox";

<Form>
  {/* @highlight-start */}
  {/* @highlight-text "name" */}
  <Field.Root name="country">
    {/* @highlight-end */}
    <Field.Label>Country of residence</Field.Label>
    <Combobox.Root />
  </Field.Root>
</Form>;

Submitting data#

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

Native submission using onSubmit

import { Form } from "@logic-ui/react/form";

<Form
  // @highlight-start
  onSubmit={async (event) => {
    // Prevent the browser's default full-page refresh
    event.preventDefault();
    // Create a FormData object
    const formData = new FormData(event.currentTarget);
    // Send the FormData instance in a fetch request
    // @highlight-end
    await fetch("https://api.example.com", {
      method: "POST",
      body: formData,
    });
  }}
/>;

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

import { Form } from "@logic-ui/react/form";

<Form
  // @highlight-start
  onFormSubmit={async (formValues) => {
    const payload = {
      product_id: formValues.id,
      order_quantity: formValues.quantity,
    };
    await fetch("https://api.example.com", {
      // @highlight-end
      method: "POST",
      body: JSON.stringify(payload),
    });
  }}
/>;

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

import { Field } from "@logic-ui/react/field";

<Field.Root name="website">
  <Field.Control type="url" required pattern="https?://.*" />
  <Field.Error />
</Field.Root>;

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

import { Field } from "@logic-ui/react/field";
import { Select } from "@logic-ui/react/select";

<Field.Root name="apple">
  <Select.Root>
    <Select.Label>Apple</Select.Label>
    <div className="relative">
      <Select.Trigger />
    </div>
  </Select.Root>
</Field.Root>;

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

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

<Field.Root
  name="username"
  {/* @highlight-start */}
  validationMode="onChange"
  validationDebounceTime={300}
  validate={async (value) => {
  // @highlight-end
    if (value === 'admin') {
      /* return an error message when invalid */
      return 'Reserved for system use.';
    }

    const result = await fetch(
      {/* prettier-ignore */},
      /* check the availability of a username from an external API */
    );

    if (!result) {
      return `${value} is unavailable.`;
    }

    /* return `null` when valid */
    return null;
  }}
>
  <Field.Control required minLength={3} />
  <Field.Error />
</Field.Root>;

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

import { Form } from '@logic-ui/react/form';
import { Field } from '@logic-ui/react/field';

async function submitToServer(/* payload */) {
  return {
    errors: { {// @highlight-text "errors"
      promoCode: 'This promo code has expired',
    },
  };
}

const [errors, setErrors] = React.useState(); // @highlight-text "errors"

<Form
  errors={errors} { // @highlight-text "errors"
  onSubmit={async (event) => {
    event.preventDefault();
    const response = await submitToServer(/* data */);
    setErrors(response.errors); // @highlight-text "errors"
  }}
>
  <Field.Root name="promoCode" />
</Form>;

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

// app/form.tsx
/* prettier-ignore */
'use client';
import { Form } from "@logic-ui/react/form";
import { Field } from "@logic-ui/react/field";
import { login } from "./actions";

// @highlight-text "state" "formAction"
const [state, formAction, loading] = React.useActionState(login, {});

// @highlight-text "state" "errors" "formAction"
<Form action={formAction} errors={state.errors}>
  <Field.Root name="password">
    <Field.Control />
    <Field.Error />
  </Field.Root>
</Form>;

// app/actions.ts
/* prettier-ignore */
'use server';
export async function login(formData: FormData) {
  const result = authenticateUser(formData);

  if (!result.success) {
    return {
      // @highlight-text "errors"
      errors: {
        password: "Invalid username or password",
      },
    };
  }
  /* redirect on the server on success */
}

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

<Field.Error match="valueMissing">You must create a username</Field.Error>

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.

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

import { useForm } from "react-hook-form";

const { control, handleSubmit } = useForm<FormValues>({
  defaultValues: {
    username: "",
    email: "",
  },
});

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

import { useForm, Controller } from "react-hook-form";
import { Field } from '@logic-ui/react/field';

const { control, handleSubmit} = useForm({
  defaultValues: {
    username: '',
  }
})

<Controller
  {/* @highlight-start */}
  name="username"
  control={control}
  render={({
    // @highlight-text "ref" "value" "onBlur" "onChange"
    field: { name, ref, value, onBlur, onChange },
    // @highlight-text "invalid" "isTouched" "isDirty" "error"
    fieldState: { invalid, isTouched, isDirty, error },
  }) => (
    {/* @highlight-text "invalid" "isTouched" "isDirty" */}
    <Field.Root name={name} invalid={invalid} touched={isTouched} dirty={isDirty}>
    {/* @highlight-end */}
      <Field.Label>Username</Field.Label>
      <Field.Description>
        May appear where you contribute or are mentioned. You can remove it at any time.
      </Field.Description>
      {/* @highlight-start */}
      <Field.Control
        placeholder="e.g. alice132"
        value={value} {/* @highlight-text "value" */}
        onBlur={onBlur} {/* @highlight-text "onBlur" */}
        onValueChange={onChange} {/* @highlight-text "onChange" */}
        ref={ref} {/* @highlight-text "ref" */}
      />
      {/* @highlight-end */}
      <Field.Error match={!!error}> {/* @highlight-text "error" */}
        {error?.message} {/* @highlight-text "error" */}
      </Field.Error>
    </Field.Root>
  )}
/>

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

import { Controller } from "react-hook-form";
import { Field } from '@logic-ui/react/field';

<Controller
  {/* @highlight-start */}
  name="username"
  control={control}
  rules={{
    required: 'This is a required field',
    minLength: { value: 2, message: 'Too short' },
    validate: (value) => {
      if (/* custom logic */) {
        return 'Invalid'
      }
      return null;
    },
    {/* @highlight-end */}
  }}
  render={({
    field: { name, ref, value, onBlur, onChange },
    fieldState: { invalid, isTouched, isDirty, error },
  }) => (
    <Field.Root name={name} invalid={invalid} touched={isTouched} dirty={isDirty}>
      <Field.Label>Username</Field.Label>
      <Field.Description>
        May appear where you contribute or are mentioned. You can remove it at any time.
      </Field.Description>
      <Field.Control
        placeholder="e.g. alice132"
        value={value}
        onBlur={onBlur}
        onValueChange={onChange}
        ref={ref}
      />
      {/* @highlight-start */}
      <Field.Error match={!!error}>
        {error?.message}
      </Field.Error>
      {/* @highlight-end */}
    </Field.Root>
  )}
/>

Submitting data#

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

Form submission handler

import { useForm } from "react-hook-form";
import { Form } from "@logic-ui/react/form";

interface FormValues {
  username: string;
  email: string;
}

const { handleSubmit } = useForm<FormValues>();

async function submitForm(data: FormValues) {
  // transform the object and/or submit it to a server
  await fetch(/* ... */);
}

<Form onSubmit={handleSubmit(submitForm)} />;

TanStack Form#

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

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

import { useForm } from '@tanstack/react-form';

interface FormValues {
  username: string;
  email: string;
}

const defaultValues: FormValues = {
  username: '',
  email: '',
};

{/* @highlight-start */}
/* useForm returns a form instance */
const form = useForm<FormValues>({
{/* @highlight-end */}
  defaultValues,
});

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

import { useForm } from '@tanstack/react-form';
import { Field } from '@logic-ui/react/field';

const form = useForm(/* defaultValues, other parameters */)

<form>
  {/* @highlight-start */}
  <form.Field
    name="username"
    children={(field) => (
    // @highlight-end
      <Field.Root
        {/* @highlight-start */}
        name={field.name} {/* @highlight-text "field.name" */}
        invalid={!field.state.meta.isValid} {/* @highlight-text "isValid" */}
        dirty={field.state.meta.isDirty} {/* @highlight-text "isDirty" */}
        touched={field.state.meta.isTouched} {/* @highlight-text "isTouched" */}
        {/* @highlight-end */}
      >
        <Field.Label>Username</Field.Label>
        <Field.Control
          {/* @highlight-start */}
          value={field.state.value} {/* @highlight-text "value" */}
          onValueChange={field.handleChange} {/* @highlight-text "handleChange" */}
          onBlur={field.handleBlur} {/* @highlight-text "handleBlur" */}
          {/* @highlight-end */}
          placeholder="e.g. bob276"
        />

        {/* @highlight-start */}
        <Field.Error match={!field.state.meta.isValid}> {/* @highlight-text "isValid" */}
        {/* @highlight-end */}
          {field.state.meta.errors.join(',')}
        </Field.Error>
      </Field.Root>
    )}
  />
</form>

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

Form validation#

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

Use the additional revalidateLogic hook and pass it to useForm.
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

import { useForm, revalidateLogic } from '@tanstack/react-form'; // @highlight-text "revalidateLogic"

const form = useForm({
  defaultValues: {
    username: '',
    email: '',
  },
  {/* @highlight-start */}
  validationLogic: revalidateLogic({ {/* @highlight-text "revalidateLogic" */}
  {/* @highlight-end */}
    mode: 'submit',
    modeAfterSubmission: 'change',
  }),
  validators: {
    // @highlight-start
    onDynamic: ({ value: formValues }) => { // @highlight-text "onDynamic"
    // @highlight-end
      const errors = {};

      if (!formValues.username) {
        errors.username = 'Username is required.';
      } else if (formValues.username.length < 3) {
        errors.username = 'At least 3 characters.';
      }

      if (!formValues.email) {
        errors.email = 'Email is required.';
      } else if (!isValidEmail(formValues.email)) {
        errors.email = 'Invalid email address.';
      }

      return { form: errors, fields: errors };
    },
  },
});

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

import { Field } from '@logic-ui/react/field';
import { useForm } from '@tanstack/react-form';

const form = useForm();

<form.Field
  name="username"
  {/* @highlight-start */}
  validators={{
    onChangeAsync: async ({ value: username }) => {
      const result = await fetch(
        /* check the availability of a username from an external API */
      );

      return result.success ? undefined : `${username} is not available.`
    }
  }}
  {/* @highlight-end */}
  children={(field) => (
    <Field.Root name={field.name} /* forward the field props */ />
  )}
>

Submitting data#

To submit the form:

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

Form submission handler

import { useForm } from '@tanstack/react-form';

const form = useForm({
  // @highlight-start
  onSubmit: async ({ value: formValues }) => {
    /* prettier-ignore */
    await fetch(/* POST the `formValues` to an external API */);
  },
  {/* @highlight-end */}
});

<form
  onSubmit={(event) => {
    event.preventDefault();
    // @highlight-start
    form.handleSubmit(); // @highlight-text "form.handleSubmit()"
    // @highlight-end
  }}
>
  {/* form fields */}
  {/* @highlight-start */}
  <button type="submit">Submit</button>
  {/* @highlight-end */}
</form>;