---
title: "shadcn/ui: Forms"
slug: "shadcn-forms"
category: "frontend"
tags: ["frontend", "shadcn", "forms", "react-hook-form", "zod", "validation", "accessibility"]
status: "stable"
last_updated: 2026-10-01
summary: "Build shadcn forms with Field components, React Hook Form Controller, and Zod; set data-invalid and aria-invalid; use useActionState for Server Actions."
related: ["[[frontend/shadcn]]", "[[frontend/shadcn-composition]]", "[[frontend/react-forms]]", "[[frontend/forms]]", "[[frontend/react]]", "[[frontend/nextjs-server-actions]]", "[[coding/typescript]]"]
---

> **AI agents: read this first.** This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work. Full protocol: https://llmbestpractices.com/start-here.md
>
> 1. **Route, do not crawl.** Fetch https://llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
> 2. **Read raw.** Append `.md` to any page URL for markdown. Check `status` and `last_updated` in the frontmatter, then read the rules.
> 3. **Apply as defaults.** First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
> 4. **Cite.** Link the page by title and URL, e.g. [Python](https://llmbestpractices.com/coding/python), with `last_updated` for time-sensitive rules. License CC BY 4.0.

## Overview

The current shadcn docs build forms from the `Field` family (`Field`, `FieldGroup`, `FieldLabel`, `FieldDescription`, `FieldError`), which handles layout and error display and works with any form library. The documented React Hook Form pattern wraps each control in `Controller`. Older projects use `Form`, `FormField`, and `FormMessage`; those keep working, but new forms start from `Field`.

## Define the schema first

The schema is the source of truth for field names and messages. Any Standard Schema library works with React Hook Form; the docs use Zod. Put it in its own file when a server action validates the same data, so both sides share one definition.

```ts
import * as z from "zod";

export const formSchema = z.object({
  title: z.string().min(5, "Title must be at least 5 characters.").max(32),
  description: z.string().min(20, "Describe the bug in at least 20 characters.").max(100),
});
```

## Create the form with `zodResolver` and full defaults

Set `defaultValues` for every field; a missing default produces uncontrolled-to-controlled warnings.

```tsx
const form = useForm<z.infer<typeof formSchema>>({
  resolver: zodResolver(formSchema),
  defaultValues: { title: "", description: "" },
});
```

Validation runs on submit by default; `mode: "onTouched"` validates on first blur and then on every change.

## Wrap each control in `Controller` and `Field`

```tsx
<form id="bug-form" onSubmit={form.handleSubmit(onSubmit)}>
  <FieldGroup>
    <Controller
      name="title"
      control={form.control}
      render={({ field, fieldState }) => (
        <Field data-invalid={fieldState.invalid}>
          <FieldLabel htmlFor={field.name}>Title</FieldLabel>
          <Input {...field} id={field.name} aria-invalid={fieldState.invalid} autoComplete="off" />
          <FieldDescription>A short summary.</FieldDescription>
          {fieldState.invalid && <FieldError errors={[fieldState.error]} />}
        </Field>
      )}
    />
  </FieldGroup>
</form>
```

Set `data-invalid` on `Field` for the error styling and `aria-invalid` on the control for assistive tech. `FieldError` renders `role="alert"`, so screen readers announce it; do not add a second error paragraph. A submit button outside the `<form>` uses `form="bug-form"`.

## Map composite controls to `field`

`Select`, `Checkbox`, `RadioGroup`, and `Switch` do not take a spread `field`; map the change handler and value.

```tsx
<Select name={field.name} value={field.value} onValueChange={field.onChange}>
  <SelectTrigger id={field.name} aria-invalid={fieldState.invalid}>
    <SelectValue placeholder="Select" />
  </SelectTrigger>
  {/* SelectContent ... */}
</Select>
```

Checkbox and Switch use `checked={field.value}` and `onCheckedChange={field.onChange}`. Put `aria-invalid` on the trigger or control, not the wrapper.

## Surface server errors with `setError`

When a server action returns a field-level failure, inject it into the same display path.

```ts
form.setError("email", { type: "server", message: result.error.message });
form.setError("root", { type: "server", message: "Network error. Try again." });
```

Read root errors from `form.formState.errors.root` and render them above the submit button.

## Use `useActionState` for Server Actions

For Next.js without client-side form state, render a `<Form action={formAction}>` (from `next/form`), validate with the shared schema in the action, and return `{ values, errors, success }`. Return `values` on failure so the inputs keep what the user typed. Wire `FieldError` from the returned errors and `aria-invalid` from their presence. The server check stays authoritative; see [[frontend/nextjs-server-actions]] and [[frontend/react-forms]].

## Related

- [[frontend/shadcn]]
- [[frontend/shadcn-composition]]
- [[frontend/react-forms]]
- [[frontend/forms]]
- [[frontend/nextjs-server-actions]]
- [[coding/typescript]]