Form

A complete form system built on React Hook Form with Zod validation. The Form component provides context for all form inputs, handles validation, and manages submission state.

Component structure

The Form system uses a compound component pattern:

Component	Description
`Form`	Complete form wrapper (combines Root + Content)
`Form.Root`	Context provider only (no DOM element)
`Form.Content`	The `<form>` element
`Form.Field`	Field wrapper with label, description, error display
`Form.Input`	Text input (used inside Form.Field)
`Form.Textarea`	Textarea (used inside Form.Field)
`Form.Checkbox`	Checkbox (used inside Form.Field)
`Form.Switch`	Toggle switch (used inside Form.Field)
`Form.RadioGroup`	Radio button group (used inside Form.Field)
`Form.InputGroup`	Input with addons (icons, buttons, text)
`Form.InputGroupInput`	Text input inside InputGroup
`Form.InputGroupAddon`	Addon container for icons/text
`Form.DatePicker`	Date picker (used inside Form.Field)
`Form.SubmitButton`	Submit button with automatic loading state

Basic usage

Use Form.Field to wrap form inputs with label, description, and error handling. The field passes its name and required state to child inputs via context.

<Form onSubmit={handleSubmit}>
  <Form.Field name="email" label="Email">
    <Form.Input />
  </Form.Field>
  <Form.Field name="password" label="Password">
    <Form.Input type="password" />
  </Form.Field>
  <Form.SubmitButton>Sign In</Form.SubmitButton>
</Form>

Form.Field props

Prop	Type	Default	Description
`name`	`string`	—	Field name (required)
`label`	`ReactNode`	—	Label text
`description`	`ReactNode`	—	Helper text below input
`required`	`boolean`	—	Show required indicator and validate
`orientation`	`'vertical' \| 'horizontal'`	`'vertical'`	Layout direction
`controlFirst`	`boolean`	—	Put input before label (for checkboxes)

For advanced layouts (card-style checkboxes, radio cards), see Field.

Form inputs

Form inputs connect to their parent Form.Field context automatically. Add validation with required on the Field.

<Form onSubmit={(data) => console.table(data)} className="w-full max-w-md">
  <Form.Field name="name" label="Name" required>
    <Form.Input placeholder="John Doe" />
  </Form.Field>
  <Form.Field name="bio" label="Bio" required>
    <Form.Textarea placeholder="Tell us about yourself" />
  </Form.Field>
  <Form.Field name="amount" label="Amount" required>
    <Form.InputGroup>
      <Form.InputGroupAddon>
        <DollarSign />
      </Form.InputGroupAddon>
      <Form.InputGroupInput placeholder="0.00" />
      <Form.InputGroupAddon align="inline-end">USD</Form.InputGroupAddon>
    </Form.InputGroup>
  </Form.Field>
  <Form.Field name="darkMode" label="Dark mode" orientation="horizontal">
    <Form.Switch />
  </Form.Field>
  <Form.Field name="plan" label="Plan">
    <Form.RadioGroup defaultValue="free">
      <HStack gap={4}>
        <label className="flex items-center gap-2">
          <Form.RadioGroupItem value="free" /> Free
        </label>
        <label className="flex items-center gap-2">
          <Form.RadioGroupItem value="pro" /> Pro
        </label>
        <label className="flex items-center gap-2">
          <Form.RadioGroupItem value="enterprise" /> Enterprise
        </label>
      </HStack>
    </Form.RadioGroup>
  </Form.Field>
  <Form.Field
    name="newsletter"
    label="Subscribe to newsletter"
    orientation="horizontal"
    controlFirst
  >
    <Form.Checkbox />
  </Form.Field>
  <Form.SubmitButton>Submit</Form.SubmitButton>
</Form>

Horizontal layout

Use orientation="horizontal" to display label and input side by side. For switches and checkboxes, add controlFirst to place the control before the label.

<Form className="w-full max-w-lg">
  <VStack gap={6}>
    <Form.Field
      name="email"
      label="Email"
      description="We'll never share your email"
      orientation="horizontal"
    >
      <Form.Input placeholder="you@example.com" />
    </Form.Field>

    <Form.Field
      name="fullName"
      label="Full name"
      description="The one you use every day"
      orientation="horizontal"
      required
    >
      <Form.Input placeholder="Jane Doe" />
    </Form.Field>

    <Form.Field
      name="notifications"
      label="Email notifications"
      description="Receive updates via email"
      orientation="horizontal"
    >
      <Form.Switch />
    </Form.Field>

    <Form.Field
      name="marketing"
      label="Marketing emails"
      orientation="horizontal"
    >
      <Form.Switch />
    </Form.Field>
    <Form.Field
      name="control_first"
      label="Control First"
      orientation="horizontal"
      controlFirst
    >
      <Form.Switch />
    </Form.Field>
  </VStack>
</Form>

Validation with Zod

Pass a Zod schema to enable validation. Errors display automatically on the corresponding inputs.

import { z } from 'zod'

const schema = z.object({
  email: z.string().email('Invalid email'),
  password: z.string().min(8, 'Must be at least 8 characters'),
})

<Form schema={schema} onSubmit={handleSubmit}>
  <Form.Field name="email" label="Email">
    <Form.Input />
  </Form.Field>
  <Form.Field name="password" label="Password">
    <Form.Input type="password" />
  </Form.Field>
  <Form.SubmitButton>Sign In</Form.SubmitButton>
</Form>

Submit button outside form

When the submit button needs to be outside the <form> element (e.g., in a sticky action bar), use Form.Root and Form.Content separately. The submit button automatically connects via the HTML form attribute.

<Form.Root schema={schema} onSubmit={handleSubmit}>
  <Form.Content>
    <Form.Field name="email" label="Email">
      <Form.Input />
    </Form.Field>
    <Form.Field name="name" label="Name">
      <Form.Input />
    </Form.Field>
  </Form.Content>

  <ActionBar>
    <Form.SubmitButton>Save Changes</Form.SubmitButton>
  </ActionBar>
</Form.Root>

Form.Root — Provides form context (react-hook-form) without rendering a DOM element
Form.Content — Renders the <form> element with the connected id
Form.SubmitButton — Uses the form attribute to submit from anywhere within Form.Root

The standard Form component composes these internally:

<Form schema={schema} onSubmit={handleSubmit}>
  <Form.Field name="email" label="Email">
    <Form.Input />
  </Form.Field>
  <Form.SubmitButton>Save</Form.SubmitButton>
</Form>

Is equivalent to:

<Form.Root schema={schema} onSubmit={handleSubmit}>
  <Form.Content>
    <Form.Field name="email" label="Email">
      <Form.Input />
    </Form.Field>
    <Form.SubmitButton>Save</Form.SubmitButton>
  </Form.Content>
</Form.Root>

External form instance

For advanced control, create the form instance yourself and pass it to Form:

import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'

const form = useForm({
  resolver: zodResolver(schema),
  defaultValues: { email: '' },
})

// Access form state
const isDirty = form.formState.isDirty

<Form form={form} onSubmit={handleSubmit}>
  <Form.Field name="email" label="Email">
    <Form.Input />
  </Form.Field>
  <Form.SubmitButton disabled={!isDirty}>Save</Form.SubmitButton>
</Form>