Docs
Forms

Forms

How to build accessible forms with Kanpeki.

Architecture

Kanpeki's form system is built on three layers:

Field (Layout)

Field is the composition and layout root. It owns:

Label placement and styling
Description text
Error message rendering
Visual structure and orientation

<Field.Root>
  <Field.Label>Email</Field.Label>
  {/* control */}
  <Field.Description>Helper text</Field.Description>
  <Field.Error />
</Field.Root>

TextField (Behavior)

TextField is a React Aria component that provides:

Automatic ID wiring (label, description, error)
Validation state
Keyboard and focus handling
ARIA attributes

TextField is composed into Field using the render prop:

<Field.Root render={<TextField type="email" isRequired />}>
  <Field.Label>Email</Field.Label>
  <Input />
  <Field.Description>We'll never share your email.</Field.Description>
  <Field.Error />
</Field.Root>

Form (Coordination)

Form is a minimal wrapper that handles:

Submission via onSubmit
Server-side validation errors
Reset handling

Form does not manage fields or control layout.

Composition Pattern

The recommended pattern composes TextField into Field:

<Form onSubmit={handleSubmit}>
  <Field.Root render={<TextField name="email" type="email" isRequired />}>
    <Field.Label>Email</Field.Label>
    <Input placeholder="john@example.com" />
    <Field.Description>We'll never share your email.</Field.Description>
    <Field.Error />
  </Field.Root>
  <Button type="submit">Submit</Button>
</Form>

Without TextField

You can use Field with Input directly, but you lose React Aria's automatic ID wiring:

<Field.Root>
  <Field.Label htmlFor="email">Email</Field.Label>
  <Input id="email" aria-describedby="email-desc" />
  <Field.Description id="email-desc">Helper text</Field.Description>
</Field.Root>

This requires manual htmlFor, id, and aria-describedby attributes.

Libraries

Choose a form library based on your needs:

TanStack Form

React Hook Form

React Aria

useActionState

(Coming Soon)

Tooltip TanStack Form

On This Page

Architecture
Field (Layout)
TextField (Behavior)
Form (Coordination)
Composition Pattern
Without TextField
Libraries

Contribute