Form

A form is a group of inputs that allows users to submit data to a server, with support for providing field validation errors.

Example

Form.tsx

Form.css

Example

Form.tsx

Form.css

import {Form} from './Form';
import {TextField} from './TextField';
import {Button} from './Button';

<Form>
  <TextField label="Name" name="name" isRequired />
  <TextField label="Email" name="email" type="email" isRequired />
  <div style={{display: 'flex', gap: 8}}>
    <Button type="submit">Submit</Button>
    <Button type="reset">Reset</Button>
  </div>
</Form>

Submitting data

When using React 19, use the action prop to handle form submission. This receives a FormData object containing the values for each form field. In React 18 or earlier, use the onSubmit event instead. See the Forms guide details about integrating with frameworks.

import {Form} from './Form';
import {TextField} from './TextField';
import {Button} from './Button';

<Form
  action={formData => {
    let name = formData.get('name');
    alert(`Hello, ${name}!`);
  }}>
  <TextField name="name" label="Name" />
  <Button type="submit">Submit</Button>
</Form>

Validation

Use validation props on each form field to prevent submission of invalid values. When validationBehavior="aria", form submission will not be prevented and validation will occur as the value is edited instead of on form submission. See the Forms guide for more details.

validationBehavior

Example

Form.tsx

Form.css

Example

Form.tsx

Form.css

import {Form} from './Form';
import {TextField} from './TextField';
import {Button} from './Button';

<Form>
  <TextField
    label="Username"
    isRequired
    validate={value => value === 'admin' ? 'Nice try.' : null}
    name="username"
    defaultValue="admin" />
  <Button type="submit">Submit</Button>
</Form>

Server validation

Use the validationErrors prop to provide server validation errors to the fields within a <Form>.

import {Form} from './Form';
import {TextField} from './TextField';

<Form
  validationErrors={{
    username: 'This username is not available.'
  }}>
  <TextField
    name="username"
    label="Username"
    defaultValue="admin" />
</Form>

Focus management

By default, after a user submits a form with validation errors, the first invalid field will be focused. To prevent this, call preventDefault() in the onInvalid event. This example moves focus to an alert at the top of the form.

import {Form} from './Form';
import {TextField} from './TextField';
import {Button} from './Button';
import {useState} from 'react';

function Example() {
  let [isInvalid, setInvalid] = useState(false);

  return (
    <Form
      onInvalid={e => {
        e.preventDefault();
        setInvalid(true);
      }}
      onSubmit={e => {
        e.preventDefault();
        setInvalid(false);
      }}
      onReset={() => setInvalid(false)}>
      {isInvalid &&
        <div role="alert" tabIndex={-1} ref={e => e?.focus()}>
          <h3>Unable to submit</h3>
          <p>Please fix the validation errors below, and re-submit the form.</p>
        </div>
      }
      <TextField
        name="firstName"
        isRequired
        label="First Name" />
      <TextField
        name="lastName"
        isRequired
        label="Last Name" />
      <div style={{display: 'flex', gap: 8}}>
        <Button type="submit">Submit</Button>
        <Button type="reset">Reset</Button>
      </div>
    </Form>
  );
}

API

Name	Type
`action`	`string \| FormHTMLAttributes<HTMLFormElement>['action']`
Where to send the form-data when the form is submitted. See MDN.
`encType`	`'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain'`
The enctype attribute specifies how the form-data should be encoded when submitting it to the server. See MDN.
`method`	`'get' \| 'post' \| 'dialog'`
The HTTP method to submit the form with. See MDN.
`target`	`'_blank' \| '_self' \| '_parent' \| '_top'`
The target attribute specifies a name or a keyword that indicates where to display the response that is received after submitting the form. See MDN.
`autoCapitalize`	`'off' \| 'none' \| 'on' \| 'sentences' \| 'words' \| 'characters'`
Controls whether inputted text is automatically capitalized and, if so, in what manner. See MDN.
`children`	`ReactNode`
The children of the component.

Default className: react-aria-Form