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, subscription-only watches, unguarded valueAsNumber, and ?? undefined controlled values 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.

Mental model: subscriptions decide who re-renders

RHF is uncontrolled at heart. Values live in refs; nothing re-renders unless a subscription says so. Every read API is a subscription decision:

Two facts explain most of the bugs we've shipped:

1. form.watch() and form.formState hoist their subscription to the useForm owner, no matter which component calls them. A child that reads form.watch('x') off a prop works today only because the whole tree re-renders on every change — it silently goes stale the moment anyone adds React.memo between owner and child, and until then it re-renders every sibling on every keystroke. A no-arg form.watch() sets watchAll and re-renders the tree on every field change for the life of the form.
2. formState is a Proxy — reading a property is what arms the subscription. Destructure it (const { isDirty } = form.formState), never pass the object around or read it conditionally (a && formState.isValid may never subscribe). Enforced by react-hook-form/destructuring-formstate (error).

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 }). Inside <Form {...form}> (which is FormProvider), useFormContext() + useWatch({ name }) also works and avoids prop-drilling entirely.
• 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.

// ❌ common in the codebase — all three subscriptions hoist to the form owner
function Fields({ form }: { form: UseFormReturn<FormValues> }) {
  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<FormValues> }) {
  const [storageType, totalSize] = useWatch({ control, name: ['storageType', 'totalSize'] })
  const { errors } = useFormState({ control })
  ...
}

The canonical form

zod schema → z.infer type → useForm with zodResolver and complete defaultValues → <Form {...form}> → FormField render-prop per field → FormItemLayout → FormControl → 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.

// 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(1, 'Must be at least 1')])
    .refine((v) => v !== '', 'Max connections is required'),
})
type FormValues = z.infer<typeof FormSchema>

const defaultValues: FormValues = { name: '', maxConnections: '' }

// Inside the component
const form = useForm<FormValues>({
  resolver: zodResolver(FormSchema),
  defaultValues,
})

<Form {...form}>
  <form id={FORM_ID} onSubmit={form.handleSubmit(onSubmit)}>
    <FormField
      control={form.control}
      name="name"
      render={({ field }) => (
        <FormItemLayout layout="horizontal" label="Name">
          <FormControl>
            <Input {...field} />
          </FormControl>
        </FormItemLayout>
      )}
    />
  </form>
</Form>

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 <form> (sheet/dialog footers) use the same module-level FORM_ID via form={FORM_ID} on the button. A module-level id is only safe for singleton forms — if the component can mount more than once at a time, duplicate ids make external buttons submit the first matching form, so mint a per-instance id with useId() and share it between the <form> and its buttons.

defaultValues, server data, and reset

• Provide a complete defaultValues object — every field, no undefined. isDirty, dirtyFields, and Cancel-reset all compare against it; a missing or undefined default breaks all three, and undefined also makes React treat the input as uncontrolled (see below).
• Form populated from an API? Use the values option, not a hand-rolled effect. values reacts to the query resolving and resets the form for you; computing defaultValues from a query that may not have loaded freezes whatever happened to be in cache at mount. Add resetOptions: { keepDirtyValues: true } when a background refetch must not clobber the user's in-progress edits. keepDirtyValues preserves whatever is in formState.dirtyFields; typed edits and setValue(…, { shouldDirty: true }) populate it regardless of subscriptions, but useFieldArray operations (append/remove/move) only mark fields dirty while dirtyFields or isDirty is subscribed — so a form that combines keepDirtyValues with a field array must read one of them in the owner, or the next refetch will discard array edits. (Good examples: components/interfaces/Settings/Database/ConnectionLogging.tsx, components/interfaces/Storage/FilesBuckets/EditBucketModal.tsx.)
• After a successful mutation, re-baseline the form in onSuccess so the saved state becomes the new baseline (isDirty returns to false, Cancel now reverts to the saved values). Prefer what the server actually persisted: if the form uses values and the mutation invalidates the query, the refetch handles this for you; if the mutation returns the updated resource, reset(response). reset(submittedValues) is the fallback for APIs that store exactly what was sent — if the server normalizes or fills values, it baselines the form to data that was never saved. A bare reset() reverts to the previous defaults — wrong after a save.
• Cancel buttons call form.reset(). This only visually restores fields whose values round-trip through defined, controlled values — which is why the null rules below matter.