Forms & Validation

Build accessible forms with validation.

Forms are built from two pieces: Field, which groups a control with its label, description, and error message and wires up the accessibility relationships; and Form, which coordinates the fields and surfaces server-side errors. Both wrap Base UI primitives.

Anatomy of a field

A Field composes a label, a control, an optional description, and an error slot. The for/id and aria-describedby associations are handled for you.

import { Field, FieldLabel, FieldDescription, FieldError } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'

export default function EmailField() {
  return (
    <Field name="email">
      <FieldLabel>Email</FieldLabel>
      <Input type="email" required placeholder="you@example.com" />
      <FieldDescription>We'll only use this to send receipts.</FieldDescription>
      <FieldError />
    </Field>
  )
}

Validation

Native constraints

Standard HTML attributes - required, type, min, maxLength, pattern - are validated automatically. Point FieldError at a specific failure with match, or render the browser's default message with a bare <FieldError />:

<Field name="email">
  <FieldLabel>Email</FieldLabel>
  <Input type="email" required />
  <FieldError match="valueMissing">An email is required.</FieldError>
  <FieldError match="typeMismatch">Enter a valid email address.</FieldError>
</Field>

Custom validation

For rules HTML can't express, pass a validate function to the Field. Return a string (or array of strings) to fail, or null to pass. Control when it runs with validationMode ('onBlur' or 'onChange'):

<Field
  name="username"
  validationMode="onBlur"
  validate={(value) => (String(value).length < 3 ? 'At least 3 characters.' : null)}
>
  <FieldLabel>Username</FieldLabel>
  <Input />
  <FieldError />
</Field>

validate can be async (return a promise) which is handy for availability checks against an API.

Shake on invalid

For an extra cue when validation fails, hang the animate-shake utility off the control's invalid state. Base UI sets data-invalid on the control when the field fails validation, so put the class on the Input to shake just the control:

<Field name="email">
  <FieldLabel>Email</FieldLabel>
  <Input type="email" required className="data-invalid:motion-safe:animate-shake" />
  <FieldError />
</Field>

The shake plays once, when the field becomes invalid (the moment data-invalid is added) - not on every failed submit while it stays invalid. Gating it behind motion-safe: keeps it off for users who prefer reduced motion, per Animation.

Grouping with Fieldset

Use Fieldset and FieldsetLegend to group related fields under a shared label (an accessible <fieldset>/<legend>):

import { Fieldset, FieldsetLegend } from '@appica/ui-react/fieldset'

export default function BillingAddress() {
  return (
    <Fieldset>
      <FieldsetLegend>Billing address</FieldsetLegend>
      <Field name="street">
        <FieldLabel>Street</FieldLabel>
        <Input />
      </Field>
      <Field name="city">
        <FieldLabel>City</FieldLabel>
        <Input />
      </Field>
    </Fieldset>
  )
}

The Form wrapper

Form ties the fields together and handles submission. Its most useful job is displaying server-side errors: return them keyed by field name and pass them to errors, and each Field shows its message in place.

'use client'

import * as React from 'react'
import { Form } from '@appica/ui-react/form'
import { Field, FieldLabel, FieldError } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'
import { Button } from '@appica/ui-react/button'

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

  return (
    <Form
      errors={errors}
      onClearErrors={setErrors}
      onSubmit={async (event) => {
        event.preventDefault()
        const data = new FormData(event.currentTarget)
        const result = await signUp(data) // your server action / API call
        if (result.errors) setErrors(result.errors) // e.g. { email: 'Already taken.' }
      }}
    >
      <Field name="email">
        <FieldLabel>Email</FieldLabel>
        <Input type="email" required />
        <FieldError />
      </Field>
      <Button type="submit">Create account</Button>
    </Form>
  )
}

Inputs are uncontrolled by default - read values from FormData on submit, as above. You can still control any field with value/onValueChange (or onChange) when you need to.

`Button` does not submit unless you say so

Button renders type="button", which it inherits from Base UI's button behavior, so dropping one inside a <form> won't submit it. Write type="submit" explicitly, as every example on this page does. An explicit type always wins, because Base UI merges caller props last.

Submitting to a server action

Form renders a real <form>, so it takes an action. Every control that carries a name ends up in the FormData, including the ones that aren't native inputs: Select and Checkbox render their own hidden input for exactly this.

You don't repeat the name on the control. Field's name propagates to whatever it wraps, and it's the same key Form matches server errors against.

app/signup/actions.ts

'use server'

export async function signUp(_prev, formData: FormData) {
  const email = String(formData.get('email') ?? '')
  const plan = String(formData.get('plan') ?? '') // Select's hidden input
  const newsletter = formData.get('newsletter') === 'on' // Checkbox's

  if (await emailTaken(email)) {
    return { errors: { email: 'Already taken.' } }
  }

  await createAccount({ email, plan, newsletter })
  return { errors: {} }
}

app/signup/signup-form.tsx

'use client'

import { useActionState } from 'react'
import { Form } from '@appica/ui-react/form'
import { Field, FieldLabel, FieldError } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'
import { Checkbox } from '@appica/ui-react/checkbox'
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@appica/ui-react/select'
import { Button } from '@appica/ui-react/button'
import { signUp } from './actions'

const PLANS = { free: 'Free', pro: 'Pro' }

export function SignupForm() {
  const [state, formAction] = useActionState(signUp, { errors: {} })

  return (
    <Form action={formAction} errors={state.errors} className="flex max-w-70 flex-col gap-4">
      <Field name="email">
        <FieldLabel>Email</FieldLabel>
        <Input type="email" required />
        <FieldError />
      </Field>

      <Field name="plan">
        <FieldLabel>Plan</FieldLabel>
        <Select defaultValue="free" items={PLANS}>
          <SelectTrigger>
            <SelectValue />
          </SelectTrigger>
          <SelectContent>
            <SelectItem value="free">Free</SelectItem>
            <SelectItem value="pro">Pro</SelectItem>
          </SelectContent>
        </Select>
      </Field>

      <Field name="newsletter" className="flex items-center gap-2">
        <Checkbox />
        <FieldLabel className="mb-0">Email me product updates</FieldLabel>
      </Field>

      <Button type="submit">Create account</Button>
    </Form>
  )
}

Returning { errors } from the action feeds Form, which routes each message to the Field whose name matches, so server-side validation renders in the same place as client-side validation.

items on Select is what lets the closed trigger show "Free" rather than the raw free. It's needed because the SelectItems live in a portal that isn't mounted while the popup is closed - see Select.

Accessibility

Labels, descriptions, and error messages are associated with their control automatically, and invalid fields are marked with aria-invalid. See Accessibility - and note that grouped controls (RadioGroup, CheckboxGroup) are labeled with aria-label/aria-labelledby, not FieldLabel.

Getting Started

Guides

Utilities