React Hook Form Patterns

Quick Guide: register binds native inputs and keeps them uncontrolled; Controller wraps components that hold their own value; useFieldArray drives repeatable rows and is keyed on field.id. Validation arrives either as register rules or as a schema through resolver. Re-renders are the thing to watch: useWatch and useFormState subscribe to named fields, whereas watch() and a wide formState destructure subscribe to the whole form.

Detailed Resources:

• examples/core.md — a type-safe form with register, error display and accessibility attributes
• examples/controlled-components.md — Controller around a select, a date picker and a checkbox group
• examples/validation.md — wiring a schema in through resolver
• examples/arrays.md — useFieldArray line items with a live total
• examples/performance.md — isolated subscriptions, FormStateSubscribe, useWatch exact and compute
• examples/form-options.md — the values prop for async data, disabled, the <Form /> component
• examples/wizard.md — multi-step form with per-step trigger()
• reference.md — decision trees, API tables, version-to-feature lookup

Which path applies

• A native `input`, `select` or `textarea` — register hands the ref to the form, the field

stays uncontrolled, and typing re-renders nothing. Follow examples/core.md.

• A component that owns its value — a custom select, date picker or rich text editor exposes no

usable ref, so Controller supplies value and onChange and confines the re-render to that field. Follow examples/controlled-components.md.

• Validation stated as a schema rather than as `register` rules — pass it through resolver and

the field-level rules drop out. Follow examples/validation.md.

<critical_requirements>

Before writing React Hook Form code

Call `useForm<FormData>()` with a generic and with `defaultValues` for every field. The generic types each field path and the submit payload; the defaults mount every input controlled from the first render.

Key `useFieldArray` rows on `field.id`. It is the identity RHF assigns the row and it survives add, remove and reorder, which an array index does not.

Reach for `Controller` as soon as a component holds its own value. register needs a ref that reaches a native input, and a component that does not forward one never joins the form.

Set `mode` to `"onBlur"` or `"onTouched"`. The default "onSubmit" withholds feedback until the first submit, and "onChange" validates on every keystroke.

Pass schema validation through `resolver`, with the schema in its own module. A schema outside the component is testable on its own and reusable across forms, and the form keeps only the wiring.

</critical_requirements>

Auto-detection: react-hook-form, useForm, register, handleSubmit, formState, Controller, useFieldArray, useWatch, useFormContext, useFormState, FormProvider, FormStateSubscribe, SubmitHandler, resolver, shouldUnregister, valueAsNumber

Applies to:

• Form state, submission and validation wiring in React
• Repeatable field groups that add, remove and reorder
• Components that hold their own value and need bridging into the form
• Multi-step flows where one form spans several screens
• Narrowing re-renders in a form with many fields

Handled elsewhere:

• Authoring the validation schema — resolver accepts a schema object and this skill only wires it

in; how the schema states its rules is settled by whatever owns it.

• Where the initial values came from — the form receives them as a prop or through the values

option and fetches nothing itself.

• Markup and styling of the inputs — every example uses plain elements, so the class names are yours.

<philosophy>

Form state lives outside React state. Inputs register themselves with the form and report through a ref, so a keystroke updates the form's own store without re-rendering the component that owns the field. Everything that reads form state — an error message, a computed total, a submit button — opts in by subscribing to a named slice, and a component that subscribes to nothing never re-renders.

This is why the wide reads cost so much. watch() in a render body and a formState destructure that pulls six properties both subscribe to the entire form, undoing the isolation the library was built for.

</philosophy>

<patterns>

Core patterns

Pattern 1: useForm with a generic

The generic, mode and defaultValues together settle type safety, validation timing and controlled-input warnings.

const {
  register,
  handleSubmit,
  formState: { errors, isSubmitting },
} = useForm<ContactFormData>({
  mode: "onBlur",
  defaultValues: { name: "", email: "", message: "" },
});

Full code: examples/core.md

Pattern 2: Controller for components that own their value

Controller renders the field itself and hands it value and onChange. The test for which to reach for: a component whose ref forwards to a native input works with register, and anything else needs Controller.

<Controller
  name="service"
  control={control}
  rules={{ required: "Service is required" }}
  render={({ field, fieldState: { error } }) => (
    <>
      <Select {...field} options={serviceOptions} />
      {error && <span role="alert">{error.message}</span>}
    </>
  )}
/>

Full code: examples/controlled-components.md

Pattern 3: useFieldArray for repeatable rows

fields carries a generated id per row, and that is the React key. Array-level rules go on the hook, and their errors land at errors.items.root.

const { fields, append, remove } = useFieldArray({ control, name: "items" });

{fields.map((field, index) => (
  <div key={field.id}>
    <input {...register(`items.${index}.name`)} />
    <button type="button" onClick={() => remove(index)}>Remove</button>
  </div>
))}

Full code: examples/arrays.md

Pattern 4: Schema validation through resolver

resolver replaces the per-field rules: the schema decides what is valid and reports errors against field paths, and the form does the wiring.

const { register, handleSubmit } = useForm<FormData>({
  resolver: zodResolver(schema),
  mode: "onBlur",
  defaultValues: { username: "", email: "" },
});

A schema kept in its own module is testable without rendering, reusable across forms, and can state cross-field rules — matching passwords, a date range — that per-field rules cannot express.

Full code: examples/validation.md

Pattern 5: useWatch for derived values

useWatch in a child component subscribes to named fields, so only that child re-renders when they change.

function PriceDisplay({ control }: { control: Control<PricingFormData> }) {
  const [plan, seats] = useWatch({ control, name: ["plan", "seats"] });
  return <div>Total: ${PLAN_PRICES[plan] * seats}</div>;
}

The compute option narrows the subscription further — the component re-renders when the computed result changes rather than when an input to it does.

Full code: examples/performance.md Pattern 11 and Pattern 12

Pattern 6: useFormContext for nested fields

FormProvider puts the form methods on context so a nested or reused section reaches them without prop drilling. Worth it at three levels of nesting or for a section rendered more than once; below that, passing control is simpler.

<FormProvider {...methods}>
  <form onSubmit={methods.handleSubmit(onSubmit)}>
    <AddressFields prefix="shippingAddress" />
    <AddressFields prefix="billingAddress" />
  </form>
</FormProvider>

function AddressFields({ prefix }) {
  const { register } = useFormContext<CheckoutFormData>();
  return <input {...register(`${prefix}.street`)} />;
}

Full code: examples/wizard.md

Pattern 7: Loading external data

values is reactive — the form follows the data as it changes — while defaultValues is read once on mount. Pair values with resetOptions: { keepDirtyValues: true } so a background refresh does not discard what the user has typed.

useForm<FormData>({
  values: userData,
  resetOptions: { keepDirtyValues: true },
});

After a successful save, reset(data) replaces the values and the defaults together, which is what clears isDirty. reset() with no argument reverts to the original defaults — the cancel button.

Full code: examples/form-options.md Pattern 7

Pattern 8: Isolated error display

useFormState with a name re-renders only when that field's state changes, which keeps an error message from re-rendering the form around it.

function FieldError<T extends FieldValues>({ control, name }: Props<T>) {
  const { errors } = useFormState({ control, name });
  const error = errors[name];
  if (!error) return null;
  return <span role="alert">{error.message as string}</span>;
}

Full code: examples/performance.md — Pattern 5 for the hook, Pattern 10 for the FormStateSubscribe component form

</patterns>

<red_flags>

Red flags

Breaks at runtime:

• An array index as the useFieldArray key — React matches the wrong rows, so removing a middle

item shifts every value below it up one. Key on field.id.

• register on a component that holds its own value — no ref arrives, the field never registers,

and its value is absent from the submit payload. Wrap it in Controller.

• No defaultValues — inputs mount uncontrolled and flip to controlled on the first keystroke,

which React warns about and SSR reports as a hydration mismatch. Seed every field, "" included.

• A partial object handed to append, prepend or insert — the absent keys arrive as undefined

and their inputs read as uncontrolled. Pass a complete item.

• An error thrown inside onSubmit — handleSubmit does not catch it, so the rejection escapes

unhandled. Catch inside the callback.

• setValue against a field array's own name — the row ids do not move with the values. Use

replace().

Surprising behaviour:

• No generic on useForm leaves field paths and the submit payload as any, so register("emial")

is accepted in silence.

• Destructuring several formState properties subscribes to all of them, and the form then

re-renders on any change. Take only what the component reads, or isolate it with useFormState.

• watch() in a render body subscribes to every field; useWatch in a child narrows it to named ones.
• setValue without shouldValidate: true leaves the previous error on screen.
• Array-level errors sit at errors.items.root; per-item errors at errors.items[index].field.
• shouldUnregister: true discards the values of unmounted fields. Leave it false (the default)

for anything that hides fields, wizards especially.

• useWatch returns its defaultValue on the first render, before the subscription attaches.
• values is for external data that keeps changing and defaultValues for static initial values;

supplying both makes which one wins depend on resetOptions.

• Per-step validation needs trigger(fieldNames) — isValid reflects the whole form, so a wizard

gated on it is stuck on step one.

Worked before/after code for the most common of these is in reference.md.

</red_flags>