# React Hook Form
> Correct React Hook Form usage anywhere in the monorepo — data flow, subscriptions, reset, dirty state, number inputs, and controlled-input rules. Load this BEFORE writing or modifying ANY form code, adding a field to an existing form, touching watch/useWatch/formState/getValues/setValue/reset, wiring a form into a dialog or sheet, or building a submit/cancel footer — even when the change looks trivial. The codebase contains widespread RHF anti-patterns; without this skill you will copy them. For form layout and which components to use, also load studio-ui-patterns.
- Skill: `rahulxdemon/react-hook-form` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rahulxdemon/react-hook-form`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rahulxdemon/react-hook-form/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: rahulxdemon (https://skillmd.com/u/rahulxdemon)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/rahulxdemon/react-hook-form
---
# React Hook Form
How to write forms that stay correct as they grow. The existing codebase is **not**
a safe reference: `form.watch()` off prop-drilled form objects, watches,
unguarded `valueAsNumber`, `?? undefined` controlled values, and raw `register()`
spread onto plain ``s are all common in older code and all wrong. Follow
this skill, not the neighboring file.
**Policy — fix what you touch.** New code must follow these rules. When you modify
existing form code, upgrade the specific fields/hooks/components you're editing to
match (e.g. a component you touch that calls `form.watch` gets converted to
`useWatch`). Leave untouched code alone, but tell the user about anti-patterns you
noticed and didn't fix. Never add new violations: `react-hook-form/no-use-watch`
is ratcheted in Studio CI — any increase in the warning count fails the build.
## Always wire fields with `Controller` — never bare `register`, never `FormField`
Every field in this codebase is a controlled component wired through RHF's
`Controller` render prop directly. **Never spread `register('name')` onto a raw
``** as a shortcut — it bypasses the `field`/`fieldState` contract every
other rule in this skill depends on (empty-string sentinels, `fieldState.invalid`,
scoped re-renders) and is invisible to `no-use-watch`/dirty-state tooling built
around `Controller`. If you see bare `register(...)` in a diff you're touching,
convert it.
This also means: don't reach for the shadcn `Form`/`FormField`/`FormItem`/
`FormControl`/`FormLabel`/`FormMessage` context wrapper, even though it also
wraps `Controller` internally. This codebase standardizes on explicit
`Controller` + `Field`/`FieldGroup` (below) — if you find `Form`/`FormField` in
a file you're touching, convert it to match.
```tsx
// ❌ never do this
// ✅ minimum acceptable wiring
(
)}
/>
```
## Field wiring: `Field` / `FieldGroup` + explicit `Controller`
Every field is wrapped in `` inside a ``, with an explicit
`Controller` per field — no `FormProvider`/context. `fieldState` comes straight
off the render prop and is passed to `FieldError` explicitly, right next to the
`field` it belongs to:
```tsx
function MyForm() {
const id = useId();
const form = useForm({
resolver: zodResolver(FormSchema),
defaultValues,
});
return (
(
Full Name
{fieldState.error && }
)}
/>
);
}
```
This per-field `fieldState` from the `Controller` render prop is a natural fit
for the "one read path per value" and "consume what you subscribed to" rules
above — there's no separate `formState` destructure to drift out of sync,
because the error for a field lives right next to its `field` in the same
render prop.
**Always build `id`/`htmlFor` from `useId()` + `field.name` — never a bare
string literal.** Call `useId()` once per form instance (not per field) and
compose each field's id as `` `${id}-${field.name}` ``. `field.name` guarantees
uniqueness across fields in the same form; `useId()` guarantees uniqueness
across mounts of the _same_ form (two open edit dialogs, a repeated form in a
list). A literal `id="name"` works until the form renders twice, at which point
both instances share a DOM id, `htmlFor` starts pointing at whichever input
rendered first, and clicking one label can focus the wrong field. This is the
same class of bug the `FORM_ID` guidance below addresses, and can reuse the
same `useId()` call.
## Reading values, by location
- **In the component that owns `useForm`:** destructure `formState`; prefer
`useWatch` over `form.watch` even here (the `no-use-watch` rule flags every
`watch`, and `useWatch` scopes the re-render if the JSX is later extracted).
- **In any child component or custom hook:** accept `control` (not the whole
`form`) and use `useWatch({ control, name })` / `useFormState({ control })`.
There's no `FormProvider`/context in this codebase's pattern, so `control`
must always be passed explicitly — don't reach for `useFormContext()`.
- **Consume the return value.** Never call a watch for its subscription side
effect and then read via `getValues()` — the watch list and the read list will
drift apart (it has already happened; fields silently lost reactivity). The
value you render must _be_ the value you subscribed to.
- **One read path per value per render.** Mixing `useWatch('x')` on one line and
`getValues('x')` a few lines later lets the two disagree within a single render.
- **Name what you watch.** `useWatch({ control })` with no `name` re-renders on
every keystroke in every field. Subscribe to the specific names you use.
- `watch(callback)` is deprecated — use `subscribe()` for render-free listeners,
and always return its cleanup from `useEffect`.
```tsx
// ❌ common in the codebase — all three subscriptions hoist to the form owner
function Fields({ form }: { form: UseFormReturn }) {
form.watch(['storageType', 'totalSize']) // return value discarded
const { errors } = form.formState // prop-form formState
const size = form.getValues('totalSize') // non-reactive read in render
...
}
// ✅ child subscribes for itself and consumes what it watches
function Fields({ control }: { control: Control }) {
const [storageType, totalSize] = useWatch({ control, name: ['storageType', 'totalSize'] })
const { errors } = useFormState({ control })
...
}
```
## The canonical form
zod schema → `z.input` type (or `z.infer` if the schema has no coerced/
transformed fields — see "Type `FormValues`" under Number inputs) → `useForm`
with `zodResolver` and **complete**
`defaultValues` → `FieldGroup` + `Controller` + `Field`/`FieldLabel`/`FieldError`
above → primitive from `ui`.
Layout/container choices (Card vs Sheet, `layout=` variants) are covered by the
`studio-ui-patterns` skill and the demos in
`apps/design-system/registry/default/example/`
(`form-patterns-pagelayout.tsx`, `form-patterns-sidepanel.tsx`) — check them
before inventing structure.
```tsx
// data/validation-limits.ts — module level, exported, reused by schema + UI
export const POOL_VALIDATION = {
MAX_CONNECTIONS_MIN: 1,
} as const
// Module level — static references, not recreated on every render
const FORM_ID = 'pool-config-form'
const FormSchema = z.object({
name: z.string().min(1, 'Name is required'),
maxConnections: z
.union([
z.literal(''),
z.coerce
.number()
.gte(
POOL_VALIDATION.MAX_CONNECTIONS_MIN,
`Must be at least ${POOL_VALIDATION.MAX_CONNECTIONS_MIN}`,
),
])
.refine((v) => v !== '', 'Max connections is required'),
})
// z.input, not z.infer — see "Typing coerced fields" below
type FormValues = z.input
const defaultValues: FormValues = { name: '', maxConnections: '' }
// Inside the component
const id = useId()
const form = useForm({
resolver: zodResolver(FormSchema),
defaultValues,
})
(
Name
{fieldState.error && }
)}
/>
```
Define the schema, `type`, static `defaultValues`, and the form's id at module
level, outside the component. Rebuilding them per render is wasted work and
unstable references — RHF reads `defaultValues` only on the first render, but
anything else comparing against these objects sees a fresh identity each time.
When they genuinely depend on runtime data, build the schema with `useMemo` and
feed server-driven defaults through the `values` option (next section) instead
of hoisting.
Submit buttons living outside the `