Form

A native form element with consolidated error handling.

'use client';
import * as React from 'react';
import { Field } from '@base-ui/react/field';
import { Form } from '@base-ui/react/form';
import { Button } from '@base-ui/react/button';
import styles from './index.module.css';

export default function ExampleForm() {
  const [errors, setErrors] = React.useState({});
  const [loading, setLoading] = React.useState(false);

  return (
    <Form
      className={styles.Form}
      errors={errors}
      onSubmit={async (event) => {
        event.preventDefault();
        const formData = new FormData(event.currentTarget);
        const value = formData.get('url') as string;

        setLoading(true);
        const response = await submitForm(value);
        const serverErrors = {
          url: response.error,
        };

        setErrors(serverErrors);
        setLoading(false);
      }}
    >
      <Field.Root name="url" className={styles.Field}>
        <Field.Label className={styles.Label}>Homepage</Field.Label>
        <Field.Control
          type="url"
          required
          defaultValue="https://example.com"
          placeholder="https://example.com"
          pattern="https?://.*"
          className={styles.Input}
        />
        <Field.Error className={styles.Error} />
      </Field.Root>
      <Button type="submit" disabled={loading} focusableWhenDisabled className={styles.Button}>
        Submit
      </Button>
    </Form>
  );
}

async function submitForm(value: string) {
  // Mimic a server response
  await new Promise((resolve) => {
    setTimeout(resolve, 1000);
  });

  try {
    const url = new URL(value);

    if (url.hostname.endsWith('example.com')) {
      return { error: 'The example domain is not allowed' };
    }
  } catch {
    return { error: 'This is not a valid URL' };
  }

  return { success: true };
}

Anatomy

Form is composed together with Field. Import the components and place them together:

Anatomy

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

<Form>
  <Field.Root>
    <Field.Label />
    <Field.Control />
    <Field.Error />
  </Field.Root>
</Form>

Examples

Submit with a Server Function

Forms using useActionState can be submitted with a Server Function instead of onSubmit.

index.tsx index.module.css theme.css

'use client';
import * as React from 'react';
import { Field } from '@base-ui/react/field';
import { Form } from '@base-ui/react/form';
import { Button } from '@base-ui/react/button';
import styles from './index.module.css';

interface FormState {
  serverErrors?: Form.Props['errors'];
}

export default function ActionStateForm() {
  const [state, formAction, loading] = React.useActionState<FormState, FormData>(submitForm, {});

  return (
    <Form errors={state.serverErrors} action={formAction} className={styles.Form}>
      <Field.Root name="username" className={styles.Field}>
        <Field.Label className={styles.Label}>Username</Field.Label>
        <Field.Control
          type="username"
          required
          defaultValue="admin"
          placeholder="e.g. alice132"
          className={styles.Input}
        />
        <Field.Error className={styles.Error} />
      </Field.Root>
      <Button type="submit" disabled={loading} focusableWhenDisabled className={styles.Button}>
        Submit
      </Button>
    </Form>
  );
}

// Mark this as a Server Function with `'use server'` in a supporting framework like Next.js
async function submitForm(_previousState: FormState, formData: FormData) {
  // Mimic a server response
  await new Promise((resolve) => {
    setTimeout(resolve, 1000);
  });

  try {
    const username = formData.get('username') as string | null;

    if (username === 'admin') {
      return { success: false, serverErrors: { username: "'admin' is reserved for system use" } };
    }

    // 50% chance the username is taken
    const success = Math.random() > 0.5;

    if (!success) {
      return {
        serverErrors: { username: `${username} is unavailable` },
      };
    }
  } catch {
    return { serverErrors: { username: 'A server error has occurred' } };
  }

  return {};
}

Submit form values as a JavaScript object

You can use onFormSubmit instead of the native onSubmit to access form values as a JavaScript object. This is useful when you need to transform the values before submission, or integrate with 3rd party APIs.

Submission using onFormSubmit

<Form
  onFormSubmit={async (formValues: { id: string; quantity: number }) => {
    const payload = {
      product_id: formValues.id,
      order_quantity: formValues.quantity,
    };

    const response = await fetch('https://api.example.com', {
      method: 'POST',
      body: payload,
    });
  }}
/>

When used, preventDefault is called on the native submit event.

Using with Zod

When parsing the schema using schema.safeParse(), the z.flattenError(result.error).fieldErrors data can be used to map the errors to each field’s name.

index.tsx index.module.css theme.css

'use client';
import * as React from 'react';
import { z } from 'zod';
import { Field } from '@base-ui/react/field';
import { Form } from '@base-ui/react/form';
import { Button } from '@base-ui/react/button';
import styles from './index.module.css';

const schema = z.object({
  name: z.string().min(1, 'Name is required'),
  age: z.coerce.number('Age must be a number').positive('Age must be a positive number'),
});

async function submitForm(formValues: Form.Values) {
  const result = schema.safeParse(formValues);

  if (!result.success) {
    return {
      errors: z.flattenError(result.error).fieldErrors,
    };
  }

  return {
    errors: {},
  };
}

export default function Page() {
  const [errors, setErrors] = React.useState({});

  return (
    <Form
      className={styles.Form}
      errors={errors}
      onFormSubmit={async (formValues) => {
        const response = await submitForm(formValues);
        setErrors(response.errors);
      }}
    >
      <Field.Root name="name" className={styles.Field}>
        <Field.Label className={styles.Label}>Name</Field.Label>
        <Field.Control placeholder="Enter name" className={styles.Input} />
        <Field.Error className={styles.Error} />
      </Field.Root>
      <Field.Root name="age" className={styles.Field}>
        <Field.Label className={styles.Label}>Age</Field.Label>
        <Field.Control placeholder="Enter age" className={styles.Input} />
        <Field.Error className={styles.Error} />
      </Field.Root>
      <Button type="submit" className={styles.Button}>
        Submit
      </Button>
    </Form>
  );
}

API reference

errorsErrors—

Name: errors
Description: Validation errors returned externally, typically after submission by a server or a form action. This should be an object where keys correspond to the name attribute on <Field.Root>, and values correspond to error(s) related to that field.
Type: Errors | undefined

actionsRefReact.RefObject<Form.Actions | null>—

Name: actionsRef
Description: A ref to imperative actions.

validate: Validates all fields when called. Optionally pass a field name to validate a single field.
Type: React.RefObject<Form.Actions | null> | undefined
Example: // validate all fields actionsRef.current.validate(); // validate one field actionsRef.current.validate('email');

onFormSubmitfunction—

Name: onFormSubmit
Description: Event handler called when the form is submitted. preventDefault() is called on the native submit event when used.
Type: | (( formValues: Record<string, any>, eventDetails: Form.SubmitEventDetails, ) => void) | undefined

validationModeForm.ValidationMode'onSubmit'

Name: validationMode
Description: Determines when the form should be validated. The validationMode prop on <Field.Root> takes precedence over this.

onSubmit (default): validates the field when the form is submitted, afterwards fields will re-validate on change.

onBlur: validates a field when it loses focus.

onChange: validates the field on every change to its value.
Type: Form.ValidationMode | undefined
Default: 'onSubmit'

classNamestring | 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: Form.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | ((state: Form.State) => React.CSSProperties | undefined) | undefined

renderReactElement | 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: Form.State) => ReactElement) | undefined

Form.PropsHide

Re-Export of Form props as FormProps

Form.StateHide

type FormState = {}

Form.ActionsHide

type FormActions = { validate: (fieldName?: string) => void }

Form.SubmitEventDetailsHide

type FormSubmitEventDetails = {
  /** The reason for the event. */
  reason: 'none';
  /** The native event associated with the custom event. */
  event: Event;
}

Form.SubmitEventReasonHide

type FormSubmitEventReason = 'none'

Form.ValidationModeHide

type FormValidationMode = 'onSubmit' | 'onBlur' | 'onChange'

Form.ValuesHide

type FormValues = Record<string, any>