Form

Installation

npx shadcn@latest add @kanpeki/form

Overview

Form is a minimal, non-visual component that coordinates:

• Form submission via onSubmit
• Server-side validation errors via validationErrors
• Reset handling via onReset

Form does not:

• Manage field state
• Control layout
• Replace the Field component
• Render visual elements or field containers

For layout and field composition, use the Field component.

Understanding the architecture

Form is only responsible for submission and validation coordination. It does not handle:

• Individual field layout → Use Field
• Input behavior and accessibility → Use TextField or similar
• Complex form state → See Forms overview for library integrations

Recommended reading:

• Forms architecture overview – Complete explanation of the three-layer system
• Field documentation – The composition root for all form fields

Anatomy

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

<Form>
  <Field.Root render={<TextField name="email" isRequired />}>
    <Field.Label>Email</Field.Label>
    <Input />
    <Field.Error />
  </Field.Root>
  <Button type="submit">Submit</Button>
</Form>;

Form Libraries

For complex forms with client-side validation and state management, see the Forms guide:

• TanStack Form - Headless form state management
• React Hook Form - Performance-focused forms
• React Aria - Native HTML validation

Examples

Basic

Component textfield-form not found in registry.

Server Validation

Use the validationErrors prop to display server-side validation errors.

<Form validationErrors={{ email: "This email is already registered." }}>
  <Field.Root render={<TextField name="email" />}>
    <Field.Label>Email</Field.Label>
    <Input />
    <Field.Error />
  </Field.Root>
</Form>

Reset

<Form onReset={() => console.log("Form reset")}>
  <Field.Root render={<TextField name="email" />}>
    <Field.Label>Email</Field.Label>
    <Input />
  </Field.Root>
  <Button type="submit">Submit</Button>
  <Button type="reset" variant="outline">
    Reset
  </Button>
</Form>

API Reference

Form accepts all props from React Aria's Form.

Field Examples

See the following components for form integration examples:

• Checkbox
• Date Field
• Radio Group
• Select
• Switch
• Textarea
• TextField