Docs
Forms
React Aria

React Aria

Build forms with React Aria's built-in validation — no extra libraries required.

This guide shows how to build forms using React Aria's native form capabilities with Kanpeki's Field and Form components.

Approach

React Aria provides built-in form support without any additional state management library. We combine it with:

Field components for layout and accessibility
TextField for automatic ID wiring between label, input, description, and error
HTML constraint validation props (isRequired, minLength, maxLength, pattern, type)
The validate prop for custom validation logic
validationErrors on Form for server-side validation

Anatomy

<Form onSubmit={(e) => { e.preventDefault(); /* ... */ }}>
  <Field.Root
    render={
      <TextField
        name="email"
        type="email"
        isRequired
      />
    }
  >
    <Field.Label>Email</Field.Label>
    <Input placeholder="name@example.com" />
    <Field.Description>Helper text</Field.Description>
    <Field.Error />
  </Field.Root>
  <Button type="submit">Submit</Button>
</Form>

TextField is Kanpeki's React Aria behavior adapter. It automatically wires Field.Label, Field.Description, and Field.Error via aria-labelledby and aria-describedby. Notice that <Field.Error /> requires no errors prop — React Aria populates it automatically from the field's validation state. See the forms architecture for more.

Setup

No extra dependencies

React Aria Components is already included in Kanpeki. Just import from the registry:

import { Form } from "~/components/ui/form";
import { Field } from "~/components/ui/field";
import { TextField } from "~/components/ui/text-field";
import { Input } from "~/components/ui/input";
import { Button } from "~/components/ui/button";

Create your form

Use <Form> and collect values from FormData on submit:

<Form
  onSubmit={(e) => {
    e.preventDefault();
    const data = Object.fromEntries(new FormData(e.currentTarget));
    console.log(data);
    e.currentTarget.reset();
  }}
>
  <Field.Root render={<TextField name="title" isRequired minLength={5} />}>
    <Field.Label>Title</Field.Label>
    <Input placeholder="Enter title" />
    <Field.Error />
  </Field.Root>
  <Button type="submit">Submit</Button>
</Form>

Validation

Constraint props

React Aria integrates with HTML constraint validation. Pass constraints directly on the field component:

Prop	Description
`isRequired`	Field must have a value before submitting
`minLength` / `maxLength`	Minimum and maximum text length
`pattern`	Custom regular expression
`type="email"` / `type="url"`	Built-in format validation
`minValue` / `maxValue`	Min and max for number or date fields

<Field.Root
  render={
    <TextField
      name="email"
      type="email"
      isRequired
    />
  }
>
  <Field.Label>Email</Field.Label>
  <Input placeholder="name@example.com" />
  <Field.Error />
</Field.Root>

Custom validation

Use the validate prop for rules that go beyond built-in constraints. Return an error string to mark the field invalid, or null to indicate it's valid:

<Field.Root
  render={
    <TextField
      name="username"
      isRequired
      validate={(value) =>
        value === "admin" ? "That username is reserved." : null
      }
    />
  }
>
  <Field.Label>Username</Field.Label>
  <Input placeholder="Choose a username" />
  <Field.Error />
</Field.Root>

Displaying errors

<Field.Error /> requires no props when used inside a <Field.Root /> with a React Aria field as the render prop. Errors are sourced automatically from the field's validation state and cleared as the user corrects input:

<Field.Root render={<TextField name="email" type="email" isRequired />}>
  <Field.Label>Email</Field.Label>
  <Input type="email" />
  <Field.Error /> {/* No errors prop needed */}
</Field.Root>

Validation behavior

By default (validationBehavior="native"), invalid fields prevent form submission. Use validationBehavior="aria" to report errors to assistive technologies without blocking submission:

<TextField
  name="email"
  type="email"
  isRequired
  validationBehavior="aria"
/>

Server Validation

Pass server-returned errors to the validationErrors prop on <Form>. React Aria clears each field's error as the user modifies its value:

Preview

Code

const [{ errors }, formAction, isPending] = useActionState(serverAction, {});

<Form
  action={formAction} 
  validationErrors={errors} 
>
  <Field.Root render={<TextField isRequired name="username" />}>
    <Field.Label>Username</Field.Label>
    <Input placeholder="Enter your username" />
    <Field.Error />
  </Field.Root>
  <Button isDisabled={isPending} type="submit">
    {isPending ? "Signing in..." : "Sign in"}
  </Button>
</Form>

validationErrors accepts an object mapping each field's name to one or more error messages:

// From your server action:
return {
  errors: {
    username: "Sorry, this username is taken.",
    email: ["Invalid format.", "Must be a company email."],
  },
};

Always validate on the server regardless of client-side constraints. Client validation is for UX; server validation is for security.

Field Types

Input

Preview

Code

Textarea

Preview

Code

Select

Preview

Code

Pass <Select.Root /> as the render prop on <Field.Root />. Use isRequired for constraint validation:

<Field.Root
  render={
    <Select.Root
      name="country"
      isRequired
      placeholder="Select a country"
    />
  }
>
  <Field.Label>Country</Field.Label>
  <Select.Trigger>
    <Select.Value />
  </Select.Trigger>
  <Popover.Content>
    <Listbox.Root>{/* items */}</Listbox.Root>
  </Popover.Content>
  <Field.Error />
</Field.Root>

Checkbox

Preview

Code

For individual checkboxes, pass <Checkbox.Provider /> as the render prop. Use the name and value props so checkbox values are included in FormData:

<Field.Root
  orientation="horizontal"
  render={
    <Checkbox.Provider
      name="notifications"
      value="email"
    />
  }
>
  <Checkbox.Root>
    <Checkbox.Indicator />
  </Checkbox.Root>
  <Field.Label>Email notifications</Field.Label>
</Field.Root>

Switch

Preview

Code

For switches, use useId() to manually wire the label via htmlFor, and provide name and value for form submission:

const id = useId();

<Field.Root orientation="horizontal">
  <Field.Content>
    <Field.Title>
      <Field.Label htmlFor={id}>Marketing emails</Field.Label>
    </Field.Title>
    <Field.Description>
      Receive emails about new products and features.
    </Field.Description>
  </Field.Content>
  <Switch.Root id={id} name="marketing" value="on">
    <Switch.Track>
      <Switch.Thumb />
    </Switch.Track>
  </Switch.Root>
</Field.Root>

Submit Button State

Use useActionState (React 19) to track submission state. The third return value isPending is true while the action is running:

const [state, formAction, isPending] = useActionState(serverAction, {});

<Form action={formAction}>
  {/* fields */}
  <Button isPending={isPending} type="submit">
    {isPending ? "Submitting..." : "Submit"}
  </Button>
</Form>

For uncontrolled forms using onSubmit, use useTransition to track pending state:

const [isPending, startTransition] = useTransition(); 

<Form
  onSubmit={(e) => {
    e.preventDefault();
    startTransition(async () => {
      await submitData(new FormData(e.currentTarget));
    })
  }}
>
  {/* fields */}
  <Button isPending={isPending} type="submit">
    {isPending ? "Submitting..." : "Submit"}
  </Button>
</Form>

Forms React Hook Form