Form

The form workspace package provides schema-driven controls for product forms and inline field surfaces. FormKit owns the submit lifecycle; FieldKit owns field state without adding a submit button. Both use Zod, React Hook Form, and the same field registry.

When to use itCopy Anchor Link

Reach for FormKit when the page has a single schema and an onSubmit. Reach for FieldKit when the parent already stores filter state (often next to a DataTable).

InstallationCopy Anchor Link

pnpm dlx shadcn@latest add https://feature-kits.vercel.app/r/form.json

pnpm add form layout ui

// apps/your-app/package.json
"dependencies": {
    "form": "workspace:*"
    "layout": "workspace:*"
    "ui": "workspace:*"
}

// next.config.ts
transpilePackages: ["form", "layout", "ui"]

import { FormKit } from "@/lib/feature-kit/form"
import { FieldKit } from "@/lib/feature-kit/form/field-kit"
import { FormSection } from "@/lib/feature-kit/layout"

Choose an APICopy Anchor Link

FormKit and FieldKit are client components. Keep the schema and default values in the client component that renders them.

AnatomyCopy Anchor Link

FormKit is a compound component:

• FormKit — creates the form context from schema + defaultValues
• FormKit.Field — dispatches to the correct control from type
• FormKit.Actions — footer row for buttons
• FormKit.Submit / FormKit.Reset — wired to form state (isPending, dirty, etc.)

FieldKit mirrors the same Field API with mode="controlled" (default) or mode="uncontrolled".

UsageCopy Anchor Link

Basic profile formCopy Anchor Link

Field typesCopy Anchor Link

FormKit.Field accepts a discriminated type. Supported values in this repo:

See Field types example for a live matrix.

ValidationCopy Anchor Link

Pass a Zod schema to FormKit. The resolver validates before onSubmit runs and focuses the first invalid field. Use Zod for interaction feedback, but keep authoritative business validation on the server.

const schema = z.object({
  email: z.string().email("Enter a valid email"),
  terms: z.boolean().refine(Boolean, "Accept the terms"),
})

The validation example demonstrates string, numeric-string, regex, range, and boolean rules.

Filter row (FieldKit)Copy Anchor Link

Use FieldKit when there is no form submit—only value changes:

import { FieldKit } from "form/field-kit"
import { z } from "zod"

const filterSchema = z.object({
  q: z.string(),
  status: z.enum(["all", "active", "archived"]),
})

<FieldKit
  schema={filterSchema}
  values={filters}
  onValuesChange={setFilters}>
  <FieldKit.Field type="text" name="q" label="Search" />
  <FieldKit.Field type="select" name="status" label="Status" options={statusOptions} />
</FieldKit>

RecipesCopy Anchor Link

Server validation errorsCopy Anchor Link

Map API failures with mapServerError or call applyServerErrors from the form package after a failed mutation. FormKit calls the mapper when onSubmit throws, applies field/form errors, and focuses the first invalid field. The mapper returns the public MapServerErrorResult shape; the package also exports mapUnknownServerError, resolveFieldErrorMessage, and focusFirstError.

Do not call an undocumented form method to set errors. Throw the mutation error from onSubmit and provide mapServerError, or use applyServerErrors(form.setError, mapped) in a custom React Hook Form integration.

Multi-section pagesCopy Anchor Link

Set scrollBody={false} on FormKit when sections live in a parent scroll container (long settings pages). Wrap each group in FormSection from layout.

Loading and pending statesCopy Anchor Link

Use isPending for an external mutation state. FormKit.Submit also disables itself while React Hook Form is submitting and displays pendingLabel. FormKit.Reset is disabled while isPending. For initial data loading, render the appropriate Field*Skeleton export before mounting the editable form; skeletons are separate controls, not a FormKit prop.

FieldKitCopy Anchor Link

FieldKit is useful when the host owns the values:

<FieldKit
  schema={filterSchema}
  mode="controlled"
  values={filters}
  onValuesChange={setFilters}>
  <FieldKit.Field type="text" name="q" label="Search" />
</FieldKit>

Controlled mode uses values and onValuesChange. Uncontrolled mode uses defaultValues; mode defaults to "uncontrolled" in the implementation. FieldKit has no submit, reset, or success lifecycle. See the FieldKit example for a controlled filter surface.

API referenceCopy Anchor Link

FormKitCopy Anchor Link

FieldKitCopy Anchor Link

Advanced usageCopy Anchor Link

Reset after successCopy Anchor Link

Set resetOnSuccess to true, "keepDirtyValues", or an object of default values. true restores the original defaultValues; "keepDirtyValues" preserves edits that were made while the submission completed.

Multi-section formsCopy Anchor Link

Use FormSection from layout to group fields. Set scrollBody={false} when the surrounding page owns scrolling. FormKit.Actions places submit controls in the form action area.

Low-level field controlsCopy Anchor Link

The package exports FieldText, FieldSelect, FieldDate, FieldDateRange, FieldMonth, FieldQuarter, FieldTime, boolean/card/radio variants, skeletons, fieldRegistry, and FormFieldView. Use these when composing a custom field layout; use FormKit.Field or FieldKit.Field for normal schema-driven forms.

API and exportsCopy Anchor Link

The package export map supports:

The root package also re-exports Controller, useFormContext, useFormState, and useWatch from React Hook Form. Internal source paths under feature/form/src are not package imports.

FormKit.Submit / FormKit.ResetCopy Anchor Link

GotchasCopy Anchor Link

ExamplesCopy Anchor Link

Package exports: form, form/field-kit, form/field (low-level field components).