Form

Forms allow users to enter data that can be submitted while providing alignment and styling for form fields.

Example#

<Form maxWidth="size-3600">
  <TextField label="Email" />
  <TextField label="Password" />
  <Checkbox>Remember me</Checkbox>
</Form>

<Form maxWidth="size-3600">
  <TextField label="Email" />
  <TextField label="Password" />
  <Checkbox>Remember me</Checkbox>
</Form>

<Form maxWidth="size-3600">
  <TextField label="Email" />
  <TextField label="Password" />
  <Checkbox>
    Remember me
  </Checkbox>
</Form>

Content#

Form accepts one or more children to render as its form elements. Label alignment, positioning, and other properties are set on the Form itself and propagated to its children to generate a cohesive design. To override these top level Form props on individual children, set them directly on the child instead.

<Form maxWidth="size-3600" isRequired necessityIndicator="label">
  <TextField label="Name" />
  <TextField label="Email" />
  <TextField label="Address" isRequired={false} />
</Form>

<Form
  maxWidth="size-3600"
  isRequired
  necessityIndicator="label"
>
  <TextField label="Name" />
  <TextField label="Email" />
  <TextField label="Address" isRequired={false} />
</Form>

<Form
  maxWidth="size-3600"
  isRequired
  necessityIndicator="label"
>
  <TextField label="Name" />
  <TextField label="Email" />
  <TextField
    label="Address"
    isRequired={false}
  />
</Form>

Labeling#

Accessibility#

A label should be provided to the Form by adding either the aria-label or aria-labelledby prop, so that the element will be identified to assistive technology as a form landmark region to which assistive technology can navigate.

<h3 id="label-3">Personal Information</h3>
<Form maxWidth="size-3600" aria-labelledby="label-3">
  <TextField label="First Name" />
  <TextField label="Last Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
    <Radio value="dragons">Dragons</Radio>
  </RadioGroup>
</Form>

<h3 id="label-3">Personal Information</h3>
<Form maxWidth="size-3600" aria-labelledby="label-3">
  <TextField label="First Name" />
  <TextField label="Last Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
    <Radio value="dragons">Dragons</Radio>
  </RadioGroup>
</Form>

<h3 id="label-3">
  Personal Information
</h3>
<Form
  maxWidth="size-3600"
  aria-labelledby="label-3"
>
  <TextField label="First Name" />
  <TextField label="Last Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">
      Dogs
    </Radio>
    <Radio value="cats">
      Cats
    </Radio>
    <Radio value="dragons">
      Dragons
    </Radio>
  </RadioGroup>
</Form>

Validation#

React Spectrum supports native HTML constraint validation with customizable UI, custom validation functions, realtime validation, and integration with server-side validation errors. The Form component facilitates server-side validation by providing error messages to the fields within it.

To provide validation errors, the validationErrors prop should be set to an object that maps each field's name prop to a string or array of strings representing one or more errors. These are displayed to the user as soon as the validationErrors prop is set, and cleared after the user modifies each field's value.

<Form
  validationErrors={{ username: 'Sorry, this username is taken.' }}
  maxWidth="size-3000"
>
  <TextField label="Username" name="username" />
</Form>

<Form
  validationErrors={{
    username: 'Sorry, this username is taken.'
  }}
  maxWidth="size-3000"
>
  <TextField label="Username" name="username" />
</Form>

<Form
  validationErrors={{
    username:
      'Sorry, this username is taken.'
  }}
  maxWidth="size-3000"
>
  <TextField
    label="Username"
    name="username"
  />
</Form>

See the Forms guide to learn more about form validation in React Spectrum, including client-side validation, and integration with other frameworks and libraries.

Validation behavior#

By default, validation errors are displayed to the user in realtime as the value is edited, and do not block form submission. To enable native HTML form validation and prevent form submission when fields are invalid, set the validationBehavior prop to "native".

import {ButtonGroup, Button} from '@adobe/react-spectrum';

<Form validationBehavior="native" maxWidth="size-3000">
  <TextField label="Email" name="email" type="email" isRequired />
  <ButtonGroup>
    <Button type="submit" variant="primary">Submit</Button>
    <Button type="reset" variant="secondary">Reset</Button>
  </ButtonGroup>
</Form>

import {Button, ButtonGroup} from '@adobe/react-spectrum';

<Form validationBehavior="native" maxWidth="size-3000">
  <TextField
    label="Email"
    name="email"
    type="email"
    isRequired
  />
  <ButtonGroup>
    <Button type="submit" variant="primary">
      Submit
    </Button>
    <Button type="reset" variant="secondary">
      Reset
    </Button>
  </ButtonGroup>
</Form>

import {
  Button,
  ButtonGroup
} from '@adobe/react-spectrum';

<Form
  validationBehavior="native"
  maxWidth="size-3000"
>
  <TextField
    label="Email"
    name="email"
    type="email"
    isRequired
  />
  <ButtonGroup>
    <Button
      type="submit"
      variant="primary"
    >
      Submit
    </Button>
    <Button
      type="reset"
      variant="secondary"
    >
      Reset
    </Button>
  </ButtonGroup>
</Form>

Focus management#

By default, after a user submits a form with validation errors, the first invalid field will be focused. You can prevent this by calling preventDefault during the onInvalid event, and move focus yourself.

This example shows how to move focus to an InlineAlert using the autoFocus prop when displaying validation errors at the top of a form.

import {InlineAlert, Heading, Content} from '@adobe/react-spectrum';

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

  return (
    <Form
      validationBehavior="native"
      onInvalid={e => {
        e.preventDefault();
        setInvalid(true);
      }}      onSubmit={e => {
        e.preventDefault();
        setInvalid(false);
      }}
      onReset={() => setInvalid(false)}
      maxWidth="size-3600">
      {isInvalid &&
        <InlineAlert variant="negative" autoFocus>          <Heading>Unable to submit</Heading>
          <Content>
            Please fix the validation errors below, and re-submit the form.
          </Content>
        </InlineAlert>
      }
      <TextField label="First Name" isRequired />
      <TextField label="Last Name" isRequired />
      <ButtonGroup>
        <Button type="submit" variant="primary">Submit</Button>
        <Button type="reset" variant="secondary">Reset</Button>
      </ButtonGroup>
    </Form>
  );
}

import {
  Content,
  Heading,
  InlineAlert
} from '@adobe/react-spectrum';

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

  return (
    <Form
      validationBehavior="native"
      onInvalid={(e) => {
        e.preventDefault();
        setInvalid(true);
      }}      onSubmit={(e) => {
        e.preventDefault();
        setInvalid(false);
      }}
      onReset={() => setInvalid(false)}
      maxWidth="size-3600"
    >
      {isInvalid &&         <InlineAlert variant="negative" autoFocus>          <Heading>Unable to submit</Heading>
          <Content>
            Please fix the validation errors below, and
            re-submit the form.
          </Content>
        </InlineAlert>}
      <TextField label="First Name" isRequired />
      <TextField label="Last Name" isRequired />
      <ButtonGroup>
        <Button type="submit" variant="primary">
          Submit
        </Button>
        <Button type="reset" variant="secondary">
          Reset
        </Button>
      </ButtonGroup>
    </Form>
  );
}

import {
  Content,
  Heading,
  InlineAlert
} from '@adobe/react-spectrum';

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

  return (
    <Form
      validationBehavior="native"
      onInvalid={(e) => {
        e.preventDefault();
        setInvalid(true);
      }}      onSubmit={(e) => {
        e.preventDefault();
        setInvalid(
          false
        );
      }}
      onReset={() =>
        setInvalid(
          false
        )}
      maxWidth="size-3600"
    >
      {isInvalid &&         <InlineAlert
          variant="negative"
          autoFocus
        >          <Heading>
            Unable to
            submit
          </Heading>
          <Content>
            Please fix
            the
            validation
            errors below,
            and re-submit
            the form.
          </Content>
        </InlineAlert>}
      <TextField
        label="First Name"
        isRequired
      />
      <TextField
        label="Last Name"
        isRequired
      />
      <ButtonGroup>
        <Button
          type="submit"
          variant="primary"
        >
          Submit
        </Button>
        <Button
          type="reset"
          variant="secondary"
        >
          Reset
        </Button>
      </ButtonGroup>
    </Form>
  );
}

Props#

Visual options#

Label position and alignment#

Top label position, start label alignment

<Form
  labelPosition="top"
  labelAlign="start"
  aria-label="Top position, start alignment example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  labelPosition="top"
  labelAlign="start"
  aria-label="Top position, start alignment example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  labelPosition="top"
  labelAlign="start"
  aria-label="Top position, start alignment example"
  maxWidth="size-3600"
>
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">
      Dogs
    </Radio>
    <Radio value="cats">
      Cats
    </Radio>
  </RadioGroup>
</Form>

Side label position, start label alignment

<Form
  labelPosition="side"
  labelAlign="start"
  aria-label="Side position, start alignment example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  labelPosition="side"
  labelAlign="start"
  aria-label="Side position, start alignment example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  labelPosition="side"
  labelAlign="start"
  aria-label="Side position, start alignment example"
  maxWidth="size-3600"
>
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">
      Dogs
    </Radio>
    <Radio value="cats">
      Cats
    </Radio>
  </RadioGroup>
</Form>

Side label position, end label alignment

<Form
  labelPosition="side"
  labelAlign="end"
  aria-label="Side position, end alignment example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  labelPosition="side"
  labelAlign="end"
  aria-label="Side position, end alignment example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  labelPosition="side"
  labelAlign="end"
  aria-label="Side position, end alignment example"
  maxWidth="size-3600"
>
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">
      Dogs
    </Radio>
    <Radio value="cats">
      Cats
    </Radio>
  </RadioGroup>
</Form>

Quiet#

<Form
  isQuiet
  aria-label="Quiet example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <TextField label="Address" />
</Form>

<Form
  isQuiet
  aria-label="Quiet example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <TextField label="Address" />
</Form>

<Form
  isQuiet
  aria-label="Quiet example"
  maxWidth="size-3600"
>
  <TextField label="Name" />
  <TextField label="Address" />
</Form>

Emphasized#

<Form
  isEmphasized
  aria-label="Emphasized example"
  maxWidth="size-3600">
  <TextField label="Name"/>
  <RadioGroup label="Favorite pet" defaultValue="dogs">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  isEmphasized
  aria-label="Emphasized example"
  maxWidth="size-3600">
  <TextField label="Name"/>
  <RadioGroup label="Favorite pet" defaultValue="dogs">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  isEmphasized
  aria-label="Emphasized example"
  maxWidth="size-3600"
>
  <TextField label="Name" />
  <RadioGroup
    label="Favorite pet"
    defaultValue="dogs"
  >
    <Radio value="dogs">
      Dogs
    </Radio>
    <Radio value="cats">
      Cats
    </Radio>
  </RadioGroup>
</Form>

Disabled#

<Form
  isDisabled
  aria-label="Disabled example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  isDisabled
  aria-label="Disabled example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  isDisabled
  aria-label="Disabled example"
  maxWidth="size-3600"
>
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">
      Dogs
    </Radio>
    <Radio value="cats">
      Cats
    </Radio>
  </RadioGroup>
</Form>

Required and necessity indicator#

Optional label

<Form
  necessityIndicator="label"
  aria-label="Optional with label example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  necessityIndicator="label"
  aria-label="Optional with label example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  necessityIndicator="label"
  aria-label="Optional with label example"
  maxWidth="size-3600"
>
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">
      Dogs
    </Radio>
    <Radio value="cats">
      Cats
    </Radio>
  </RadioGroup>
</Form>

Required label

<Form
  isRequired
  necessityIndicator="label"
  aria-label="Required with label example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  isRequired
  necessityIndicator="label"
  aria-label="Required with label example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  isRequired
  necessityIndicator="label"
  aria-label="Required with label example"
  maxWidth="size-3600"
>
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">
      Dogs
    </Radio>
    <Radio value="cats">
      Cats
    </Radio>
  </RadioGroup>
</Form>

Required with asterisk

<Form
  isRequired
  necessityIndicator="icon"
  aria-label="Required with asterisk example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  isRequired
  necessityIndicator="icon"
  aria-label="Required with asterisk example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  isRequired
  necessityIndicator="icon"
  aria-label="Required with asterisk example"
  maxWidth="size-3600"
>
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">
      Dogs
    </Radio>
    <Radio value="cats">
      Cats
    </Radio>
  </RadioGroup>
</Form>

Read only#

<Form
  isReadOnly
  aria-label="isReadOnly example"
  maxWidth="size-3600">
  <TextField label="Name" value="John Smith" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  isReadOnly
  aria-label="isReadOnly example"
  maxWidth="size-3600">
  <TextField label="Name" value="John Smith" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  isReadOnly
  aria-label="isReadOnly example"
  maxWidth="size-3600"
>
  <TextField
    label="Name"
    value="John Smith"
  />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">
      Dogs
    </Radio>
    <Radio value="cats">
      Cats
    </Radio>
  </RadioGroup>
</Form>

Validation state#

<Form
  validationState="invalid"
  aria-label="Invalid validationState example"
  maxWidth="size-3600"
  marginBottom="size-300">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  validationState="invalid"
  aria-label="Invalid validationState example"
  maxWidth="size-3600"
  marginBottom="size-300">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  validationState="invalid"
  aria-label="Invalid validationState example"
  maxWidth="size-3600"
  marginBottom="size-300"
>
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">
      Dogs
    </Radio>
    <Radio value="cats">
      Cats
    </Radio>
  </RadioGroup>
</Form>

<Form
  validationState="valid"
  aria-label="Valid validationState example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  validationState="valid"
  aria-label="Valid validationState example"
  maxWidth="size-3600">
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">Dogs</Radio>
    <Radio value="cats">Cats</Radio>
  </RadioGroup>
</Form>

<Form
  validationState="valid"
  aria-label="Valid validationState example"
  maxWidth="size-3600"
>
  <TextField label="Name" />
  <RadioGroup label="Favorite pet">
    <Radio value="dogs">
      Dogs
    </Radio>
    <Radio value="cats">
      Cats
    </Radio>
  </RadioGroup>
</Form>