react-hook-form-zod

React Hook Form + Zod Validation

Status: Production Ready ✅ Last Verified: 2026-01-20 Latest Versions: [email protected], [email protected], @hookform/[email protected]

---

Quick Start

npm install [email protected] [email protected] @hookform/[email protected]

Basic Form Pattern:

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
})

// zodResolver infers types — no need for z.infer<typeof schema> on useForm
const form = useForm({
  resolver: zodResolver(schema),
  defaultValues: { email: '', password: '' }, // REQUIRED to prevent uncontrolled warnings
})

const onSubmit = form.handleSubmit((value) => {
  console.log(value)
})

<form onSubmit={onSubmit}>
  <input {...form.register('email')} />
  {form.formState.errors.email && <span role="alert">{form.formState.errors.email.message}</span>}
</form>

Server Validation (CRITICAL - never skip):

// SAME schema on server
const data = schema.parse(await req.json())

---

Key Patterns

useForm Options (validation modes):

• mode: 'onSubmit' (default) - Best performance
• mode: 'onBlur' - Good balance
• mode: 'onChange' - Live feedback, more re-renders
• shouldUnregister: true - Remove field data when unmounted (use for multi-step forms)

Zod Refinements (cross-field validation):

z.object({ password: z.string(), confirm: z.string() })
  .refine((data) => data.password === data.confirm, {
    message: "Passwords don't match",
    path: ['confirm'], // CRITICAL: Error appears on this field
  })

Zod Transforms:

z.string().transform((val) => val.toLowerCase()) // Data manipulation
z.string().transform(parseInt).refine((v) => v > 0) // Chain with refine

Zod v4.3.0+ Features:

// Exact optional (can omit field, but NOT undefined)
z.string().exactOptional()

// Exclusive union (exactly one must match)
z.xor([z.string(), z.number()])

// Import from JSON Schema
z.fromJSONSchema({ type: "object", properties: { name: { type: "string" } } })