Form

A native form element with consolidated error handling.

Base UI React 1.8.0

FineSoft Stencil

react-form.tsx stencil-form.tsx stencil-form-view.tsx index.module.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';

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

The Stencil comparison uses fs-form together with the migrated fs-field-* and fs-button elements. fs-form is a transparent custom-element host: it renders the native <form> that owns submission, native attributes, FormData, validation, and focus. Consumer classes, styles, global attributes, ARIA attributes, and data-* attributes are forwarded to that native form.

Pass form-level errors directly to fs-form; descendant fields resolve their messages by name and clear only the field being edited. validationMode is inherited by fields, and actionsRef.current.validate() validates all fields or one named field. A string action uses native browser submission. A function action receives FormData, while Stencil’s formSubmit property receives the consolidated JavaScript value object and the original submit event details. It is named without the React on prefix because React treats every on* prop on a custom element as a DOM event listener instead of assigning the function property. As in Base UI, either function API prevents the native submission after validation succeeds. formRef exposes the rendered native form.

The code panels below are the files used by the running Stencil examples. They contain all consumer state and behavior; there is no component-specific docs controller or hidden structure.

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.

Base UI React 1.8.0

FineSoft Stencil

react-form.tsx stencil-form.tsx stencil-form-view.tsx index.module.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="text"
          autoComplete="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',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(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.

Base UI React 1.8.0

FineSoft Stencil

react-form.tsx stencil-form.tsx stencil-form-view.tsx index.module.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
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
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: React.DetailedHTMLProps< React.FormHTMLAttributes<HTMLFormElement>, HTMLFormElement >, 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>