JavaScript Advanced

Building Type-Safe Forms with Zod, React Hook Form & Next.js 16

📅 April 11, 2026 ⏱ 3 min read 🎯 Advanced

Where developers are forged. · Structured learning · Free forever.

📍 Part of: React.js → Topic 24 of 32

Build fully type-safe, performant forms in Next.

🔥 Advanced — solid JavaScript foundation required

In this tutorial, you'll learn

Build fully type-safe, performant forms in Next.

Zod schema is the single source of truth — drives client validation, server validation, and TypeScript types
React Hook Form uses uncontrolled inputs — 90% fewer re-renders than useState-based forms
Server actions must re-validate with the same Zod schema — client validation is bypassable

✦ Plain-English analogy ✦ Real code with output ✦ Interview questions

⚡Quick Answer

Zod defines the validation schema — one schema drives both client and server validation
React Hook Form manages form state with minimal re-renders — 90% fewer than useState
Server Actions validate the same Zod schema on the server — no duplicate validation logic
The resolver pattern connects Zod to React Hook Form — zodResolver bridges the two
TypeScript infers the form type from the Zod schema — no manual type definitions needed
Biggest mistake: validating on client only — Server Actions must re-validate to prevent bypass

🚨 START HERE

Zod + React Hook Form Quick Debug Reference

Fast commands for diagnosing form issues

🟡Zod schema type not inferring correctly

Immediate ActionCheck the schema shape and z.infer usage

Commands

npx tsc --noEmit 2>&1 | grep -i 'zod\|schema\|infer' | head -20

cat node_modules/zod/package.json | grep version

Fix NowEnsure zod is installed and import * as z from 'zod' — check that z.infer is used on the schema variable

🟡React Hook Form not registering fields

Immediate ActionCheck that register is spread on the input element

Commands

grep -rn 'register(' components/ --include='*.tsx' | head -10

grep -rn 'Controller\|useController' components/ --include='*.tsx' | head -10

Fix NowUse {...register('fieldName')} on native inputs or <Controller> for shadcn/ui components

🟡Server Action not receiving form data

Immediate ActionCheck the form action attribute and FormData handling

Commands

grep -rn 'action={' app/ --include='*.tsx' | head -10

grep -rn 'useActionState\|useFormStatus' app/ --include='*.tsx' | head -10

Fix NowPass the server action to the form action prop — use Object.fromEntries(formData) to parse

🟡Zod discriminated union not narrowing types

Immediate ActionCheck the discriminator field is present in all union members

Commands

grep -n 'discriminatedUnion\|z.discriminatedUnion' types/*.ts lib/*.ts

npx tsc --noEmit 2>&1 | grep -i 'union\|never\|discriminat' | head -10

Fix NowEnsure every union member has the discriminator field with a literal type — z.literal('type')

Production IncidentClient-Only Zod Validation Allowed 3,200 Invalid SubscriptionsA SaaS signup form validated with Zod on the client but not on the server. A bot bypassed the client validation and submitted 3,200 subscriptions with invalid email formats and negative quantities.

SymptomThe billing dashboard showed 3,200 new subscriptions in 4 hours — far above the normal 50-100 per day. All subscriptions had email addresses like 'a@b' or 'test' and quantities of -1 or 0. The Stripe API accepted the requests because the server never validated the input.

AssumptionZod validation on the client was sufficient — users would always submit through the browser form.

Root causeThe signup form used React Hook Form with Zod validation via zodResolver. The validation worked perfectly in the browser — invalid fields showed errors and the submit button was disabled. However, the server-side API route accepted the request body directly without re-validating. A bot sent POST requests to /api/subscribe with crafted JSON payloads that bypassed the browser entirely. The server trusted the client-validated data and passed it to Stripe.

FixAdded the same Zod schema to the server action. The server action calls schema.parse(data) before processing — if validation fails, it returns field errors to the client. Added rate limiting to the API route (10 requests per minute per IP). Added honeypot fields to the form that bots fill but humans do not. The Zod schema is now the single source of truth — imported by both the client form and the server action. ``

ts
// In server action
if (formData.get('website_hp')) {
  return { errors: { root: ['Bot detected'] }, success: false }
}
// Rate limiting (example with Upstash)
const ratelimit = new Ratelimit({ redis, limiter: ... })
const { success } = await ratelimit.limit(ip)
if (!success) return { errors: { root: ['Rate limit exceeded'] }, success: false }

Key Lesson

Client validation is for UX — server validation is for security. Never trust client-validated data.The same Zod schema must be used on both client and server — define it once, import it twice.Bots bypass browser forms entirely — they send raw HTTP requests to your API endpoints.Rate limiting and honeypot fields are defense-in-depth — they do not replace server-side validation.

Production Debug GuideDiagnose common form validation and state issues

Form errors not displaying after submission→Check that FormMessage is rendered inside FormField — it reads errors from FormField context, not from useForm directly

Zod schema validation passes but server rejects the data→Compare the client Zod schema with the server Zod schema — they may have diverged. Use a single shared schema file.

Form re-renders on every keystroke→Verify you are using React Hook Form's register — not controlled state with useState. Check for useWatch on the entire form instead of specific fields.

Server Action returns errors but form does not display them→Use useActionState to receive server action results — pass the errors to form.setError() for each field

TypeScript errors on form field names→Ensure the form is typed with z.infer<typeof schema> — field names must match the Zod schema keys exactly

Form handling is where most React applications accumulate technical debt. Developers start with useState for every field, add ad-hoc validation in event handlers, and end up with 500-line form components that re-render on every keystroke. The performance degrades. The validation is inconsistent. The types drift from the actual data shape.

Zod, React Hook Form, and Next.js Server Actions solve this as a stack. Zod defines the validation schema once — it drives client validation, server validation, and TypeScript type inference. React Hook Form manages form state with near-zero re-renders. Server Actions validate the same schema on the server, preventing client-side bypass.

This article covers the integration patterns that work in production: schema-driven forms, Server Action validation, error handling, multi-step wizards, and dynamic field arrays.

Schema-Driven Forms: Zod as the Single Source of Truth

The foundation of type-safe forms is a Zod schema that defines the shape, types, and validation rules for every field. This schema is imported by the client form (via zodResolver), the server action (via schema.parse()), and TypeScript (via z.infer). One definition drives everything.

The key insight: Zod schemas are not just validators — they are type providers. z.infer<typeof schema> produces a TypeScript type that matches the validated data. If you change the schema, the type updates automatically. If you add a field, TypeScript tells you every place that needs to use it.

This eliminates the three most common form bugs: validation on client but not server, types that drift from validation rules, and fields that exist in the schema but are missing from the form.

io.thecodeforge.forms.zod-schema.ts · TYPESCRIPT

// ============================================
// Zod Schema: Single Source of Truth
// ============================================
// This file is imported by:
//   1. The client form (React Hook Form + zodResolver)
//   2. The server action (schema.parse())
//   3. TypeScript type inference (z.infer)

import * as z from 'zod'

// ---- Define the schema ----
// Each field has a type and validation rules
// The schema drives everything: validation, types, error messages

export const signupSchema = z.object({
  name: z
    .string()
    .min(2, 'Name must be at least 2 characters')
    .max(50, 'Name must be at most 50 characters'),

  email: z
    .string()
    .email('Invalid email address')
    .toLowerCase(),

  password: z
    .string()
    .min(8, 'Password must be at least 8 characters')
    .regex(/[A-Z]/, 'Password must contain an uppercase letter')
    .regex(/[0-9]/, 'Password must contain a number')
    .regex(/[^A-Za-z0-9]/, 'Password must contain a special character'),

  confirmPassword: z.string(),

  role: z.enum(['member', 'admin'], {
    errorMap: () => ({ message: 'Please select a role' }),
  }),

  acceptTerms: z
    .boolean()
    .refine((val) => val === true, {
      message: 'You must accept the terms and conditions',
    }),

  // Optional fields — may be undefined
  bio: z.string().max(500, 'Bio must be at most 500 characters').optional(),

  website: z
    .string()
    .url('Invalid URL')
    .startsWith('https://', 'URL must use HTTPS')
    .optional()
    .or(z.literal('')),

  // Nested object — Zod handles nested validation
  address: z
    .object({
      street: z.string().min(1, 'Street is required'),
      city: z.string().min(1, 'City is required'),
      state: z.string().length(2, 'Use 2-letter state code'),
      zip: z
        .string()
        .regex(/^\d{5}(-\d{4})?$/, 'Invalid ZIP code'),
    })
    .optional(),
})
// Cross-field validation — refine runs after all field validations pass
.refine((data) => data.password === data.confirmPassword, {
  message: 'Passwords do not match',
  path: ['confirmPassword'], // Error attaches to this field
})

// ---- Type inference ----
// z.infer produces a TypeScript type from the schema
// This type is used by React Hook Form and the server action
type SignupFormValues = z.infer<typeof signupSchema>

// ---- Partial schema for update forms ----
// Derive update schema from the create schema
export const updateProfileSchema = signupSchema
  .pick({
    name: true,
    bio: true,
    website: true,
    address: true,
  })
  .partial() // All fields become optional
  .refine((data) => Object.keys(data).length > 0, {
    message: 'At least one field must be provided',
  })

// ---- Login schema — simpler

export const loginSchema = z.object({
  email: z.string().email('Invalid email address'),
  password: z.string().min(1, 'Password is required'),
  rememberMe: z.coerce.boolean().default(false),
})

type LoginFormValues = z.infer<typeof loginSchema>

// ---- Invoice schema — complex nested structure ----
export const invoiceItemSchema = z.object({
  description: z.string().min(1, 'Description is required'),
  quantity: z.coerce
    .number()
    .int('Must be a whole number')
    .min(1, 'Minimum quantity is 1')
    .max(10000, 'Maximum quantity is 10,000'),
  unitPrice: z.coerce
    .number()
    .min(0.01, 'Price must be positive')
    .max(999999.99, 'Price too high'),
  taxable: z.boolean().default(false),
})

export const invoiceSchema = z.object({
  clientName: z.string().min(2, 'Client name is required'),
  clientEmail: z.string().email('Invalid email'),
  dueDate: z.string().min(1, 'Due date is required'),
  items: z
    .array(invoiceItemSchema)
    .min(1, 'Add at least one line item')
    .max(50, 'Maximum 50 line items'),
  notes: z.string().max(1000).optional(),
  paymentTerms: z.enum(['net15', 'net30', 'net60', 'due_on_receipt']),
})

type InvoiceFormValues = z.infer<typeof invoiceSchema>

Mental Model

Zod Schema as a Contract

The Zod schema is the contract between client and server — both sides validate against the same rules.

Client uses the schema via zodResolver — validates on blur and on submit
Server uses the schema via schema.parse() — validates before processing
TypeScript uses z.infer<typeof schema> — derives types automatically
Change the schema once — validation, types, and error messages update everywhere
The schema is the single source of truth — no duplicate validation logic

📊 Production Insight

Zod schemas are imported by both client and server — one definition, two validation points.

If the schemas diverge, the client accepts data the server rejects — or vice versa.

Rule: define the schema in a shared file — import it on both sides.

🎯 Key Takeaway

Zod schema is the single source of truth — drives validation, types, and error messages.

z.infer<typeof schema> produces TypeScript types automatically — no manual type definitions.

Refine for cross-field validation — password matching, conditional requirements.

React Hook Form Integration: Minimal Re-Renders

React Hook Form manages form state with uncontrolled inputs by default. It registers DOM elements directly via refs, not React state. This means typing in a field does not trigger a re-render of the form component — only the changed field updates.

The integration with Zod happens through zodResolver — a bridge that connects the Zod schema to React Hook Form's validation lifecycle. When the user submits or blurs a field, zodResolver runs the Zod validation and maps errors to the form state.

The key architectural decision: use register for native inputs (input, textarea, select) and Controller for custom components (shadcn/ui, etc.). Mixing these patterns incorrectly causes validation to silently fail.

io.thecodeforge.forms.react-hook-form.tsx · TSX

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215

// ============================================
// React Hook Form + Zod Integration
// ============================================

'use client'

import * as React from 'react'
import { useForm, Controller, useFieldArray } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { signupSchema, type SignupFormValues } from '@/lib/schemas/signup'
import {
  Form,
  FormControl,
  FormDescription,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from '@/components/ui/form'
import { Input } from '@/components/ui/input'
import { Button } from '@/components/ui/button'
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from '@/components/ui/select'
import { Checkbox } from '@/components/ui/checkbox'
import { Textarea } from '@/components/ui/textarea'

export function SignupForm() {
  const form = useForm<SignupFormValues>({
    resolver: zodResolver(signupSchema),
    defaultValues: {
      name: '',
      email: '',
      password: '',
      confirmPassword: '',
      role: 'member',
      acceptTerms: false,
      bio: '',
      website: '',
    },
    mode: 'onBlur',
    reValidateMode: 'onChange',
  })

  async function onSubmit(data: SignupFormValues) {
    try {
      const response = await fetch('/api/signup', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data),
      })

      if (!response.ok) {
        const error = await response.json()
        if (error.fieldErrors) {
          Object.entries(error.fieldErrors).forEach(([field, message]) => {
            form.setError(field as any, {
              type: 'server',
              message: message as string,
            })
          })
        }
        return
      }
    } catch (err) {
      form.setError('root', {
        type: 'network',
        message: 'Network error — please try again',
      })
    }
  }

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
        <FormField
          control={form.control}
          name="name"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Name</FormLabel>
              <FormControl>
                <Input placeholder="Alice Johnson" {...field} />
              </FormControl>
              <FormDescription>Your display name on the platform</FormDescription>
              <FormMessage />
            </FormItem>
          )}
        />

        <FormField
          control={form.control}
          name="email"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Email</FormLabel>
              <FormControl>
                <Input type="email" placeholder="alice@example.com" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <FormField
          control={form.control}
          name="password"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Password</FormLabel>
              <FormControl>
                <Input type="password" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <FormField
          control={form.control}
          name="confirmPassword"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Confirm Password</FormLabel>
              <FormControl>
                <Input type="password" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <FormField
          control={form.control}
          name="role"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Role</FormLabel>
              <Select onValueChange={field.onChange} defaultValue={field.value}>
                <FormControl>
                  <SelectTrigger>
                    <SelectValue placeholder="Select a role" />
                  </SelectTrigger>
                </FormControl>
                <SelectContent>
                  <SelectItem value="member">Member</SelectItem>
                  <SelectItem value="admin">Admin</SelectItem>
                </SelectContent>
              </Select>
              <FormMessage />
            </FormItem>
          )}
        />

        <FormField
          control={form.control}
          name="bio"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Bio (optional)</FormLabel>
              <FormControl>
                <Textarea
                  placeholder="Tell us about yourself"
                  className="resize-none"
                  {...field}
                />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <FormField
          control={form.control}
          name="acceptTerms"
          render={({ field }) => (
            <FormItem className="flex flex-row items-start space-x-3 space-y-0">
              <FormControl>
                <Checkbox
                  checked={field.value}
                  onCheckedChange={field.onChange}
                />
              </FormControl>
              <div className="space-y-1 leading-none">
                <FormLabel>Accept terms and conditions</FormLabel>
                <FormDescription>
                  You agree to our Terms of Service and Privacy Policy
                </FormDescription>
              </div>
              <FormMessage />
            </FormItem>
          )}
        />

        {form.formState.errors.root && (
          <div className="text-sm text-destructive">
            {form.formState.errors.root.message}
          </div>
        )}

        <Button
          type="submit"
          disabled={form.formState.isSubmitting}
          className="w-full"
        >
          {form.formState.isSubmitting ? 'Creating account...' : 'Sign Up'}
        </Button>
      </form>
    </Form>
  )
}

⚠ Register vs Controller: When to Use Each

📊 Production Insight

React Hook Form uses uncontrolled inputs — typing does not trigger re-renders.

This is 90% fewer re-renders than useState-based forms — visible in React DevTools.

Rule: use register for native inputs, Controller for custom components — never mix.

🎯 Key Takeaway

React Hook Form + zodResolver connects Zod to form validation — one schema, two validation points.

Use register for native inputs, Controller for custom components — mixing causes silent failures.

Server errors must be explicitly set via form.setError() — they do not appear automatically.

Server Actions: Server-Side Validation with the Same Schema

Next.js Server Actions run on the server when a form is submitted. They receive FormData, validate it against the Zod schema, and return errors or success. The critical pattern: the server action imports the same Zod schema that the client form uses. This guarantees client and server validation are always in sync.

The validation flow: client validates for UX (instant feedback), server validates for security (prevents bypass). If the client validation passes but the server rejects, it means either the client schema diverged from the server schema, or a bot bypassed the browser. Both cases need investigation.

io.thecodeforge.forms.server-action.ts · TYPESCRIPT

// ============================================
// Server Action with Zod Validation
// ============================================
// File: app/signup/actions.ts
// This file runs ONLY on the server — never sent to the client

'use server'

import { redirect } from 'next/navigation'
import { signupSchema } from '@/lib/schemas/signup'
import { prisma } from '@/lib/db'
import bcrypt from 'bcrypt'

// ---- Server Action: Signup ----
// Receives FormData from the form submission
// Validates with the SAME Zod schema as the client

export async function signupAction(
  prevState: { errors: Record<string, string[]>; success: boolean },
  formData: FormData
): Promise<{ errors: Record<string, string[]>; success: boolean }> {
  // ---- Step 1: Extract data from FormData ----
  const raw = {
    name: formData.get('name') as string,
    email: formData.get('email') as string,
    password: formData.get('password') as string,
    confirmPassword: formData.get('confirmPassword') as string,
    role: formData.get('role') as string,
    acceptTerms: formData.get('acceptTerms') === 'true',
    bio: (formData.get('bio') as string) || undefined,
    website: (formData.get('website') as string) || undefined,
  }

  // ---- Step 2: Validate with Zod (safeParse returns result, does not throw) ----
  const result = signupSchema.safeParse(raw)

  if (!result.success) {
    const fieldErrors: Record<string, string[]> = {}
    result.error.issues.forEach((issue) => {
      const path = issue.path.join('.')
      if (!fieldErrors[path]) {
        fieldErrors[path] = []
      }
      fieldErrors[path].push(issue.message)
    })

    return { errors: fieldErrors, success: false }
  }

  // ---- Step 3: Business logic validation ----
  const { email, password, name, role, bio, website } = result.data

  const existingUser = await prisma.user.findUnique({
    where: { email },
  })

  if (existingUser) {
    return {
      errors: { email: ['An account with this email already exists'] },
      success: false,
    }
  }

  // ---- Step 4: Process the valid data ----
  const passwordHash = await bcrypt.hash(password, 12)

  await prisma.user.create({
    data: {
      name,
      email,
      passwordHash,
      role,
      bio: bio ?? null,
      website: website ?? null,
    },
  })

  // ---- Step 5: Redirect on success ----
  redirect('/dashboard')
}

// ---- Server Action: Update Profile ----
// Uses a partial schema — only changed fields are validated

import { updateProfileSchema } from '@/lib/schemas/signup'

export async function updateProfileAction(
  userId: string,
  prevState: { errors: Record<string, string[]>; success: boolean },
  formData: FormData
): Promise<{ errors: Record<string, string[]>; success: boolean }> {
  const raw: Record<string, unknown> = {}

  const name = formData.get('name')
  const bio = formData.get('bio')
  const website = formData.get('website')

  if (name) raw.name = name
  if (bio) raw.bio = bio
  if (website) raw.website = website

  if (Object.keys(raw).length === 0) {
    return {
      errors: { root: ['No changes provided'] },
      success: false,
    }
  }

  const result = updateProfileSchema.safeParse(raw)

  if (!result.success) {
    const fieldErrors: Record<string, string[]> = {}
    result.error.issues.forEach((issue) => {
      const path = issue.path.join('.')
      if (!fieldErrors[path]) fieldErrors[path] = []
      fieldErrors[path].push(issue.message)
    })
    return { errors: fieldErrors, success: false }
  }

  await prisma.user.update({
    where: { id: userId },
    data: result.data,
  })

  return { errors: {}, success: true }
}

Mental Model

Client Validates for UX, Server Validates for Security

Client validation gives instant feedback — server validation prevents bypass. Both are required.

Client validation runs on blur and submit — users see errors immediately
Server validation runs on form submission — prevents bots and API bypass
Same Zod schema on both sides — structural validation is always in sync
Business rules (duplicate email, auth checks) go in the server action, not the schema
If client passes but server rejects, the schemas have diverged or the request was bypassed

📊 Production Insight

Server actions must re-validate with the same Zod schema — client validation is bypassable.

safeParse returns a result object — never use parse() in server actions (it throws).

Rule: validate on client for UX, validate on server for security — both use the same schema.

🎯 Key Takeaway

Server actions import the same Zod schema as the client — validation is always in sync.

safeParse returns { success, data, error } — map errors to field-level messages.

Business rules (duplicate email, auth) go in the server action — not in the Zod schema.

Connecting Server Actions to Forms with useActionState (React 19)

The bridge between a React form and a Server Action is useActionState (React 19). This hook wraps the server action and provides the result state to the component. The component renders errors from the server action result.

The pattern: the form's action prop points to the wrapped server action. On submit, the action runs on the server, returns a state object, and the component re-renders with the result.

io.thecodeforge.forms.use-action-state.tsx · TSX

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354

// ============================================
// Connecting Server Actions to Forms (Next.js 16 / React 19)
// ============================================

'use client'

import * as React from 'react'
import { useActionState } from 'react'
import { useFormStatus } from 'react-dom'
import { signupAction } from '@/app/signup/actions'
import { Input } from '@/components/ui/input'
import { Button } from '@/components/ui/button'
import { Label } from '@/components/ui/label'

function SubmitButton() {
  const { pending } = useFormStatus()

  return (
    <Button type="submit" disabled={pending} className="w-full">
      {pending ? 'Creating account...' : 'Sign Up'}
    </Button>
  )
}

export function SignupFormWithServerAction() {
  const [state, formAction] = useActionState(signupAction, {
    errors: {},
    success: false,
  })

  return (
    <form action={formAction} className="space-y-4">
      <div className="space-y-2">
        <Label htmlFor="name">Name</Label>
        <Input id="name" name="name" placeholder="Alice Johnson" required />
        {state.errors.name && (
          <p className="text-sm text-destructive">
            {state.errors.name.join(', ')}
          </p>
        )}
      </div>

      {/* Other fields ... */}

      {state.errors.root && (
        <div className="rounded-md bg-destructive/10 p-3 text-sm text-destructive">
          {state.errors.root.join(', ')}
        </div>
      )}

      <SubmitButton />
    </form>
  )
}

💡useActionState (React 19) vs useFormState

useActionState is the new React 19 hook — imported from 'react'
useFormState (from 'react-dom') is deprecated in React 19
useActionState returns [state, formAction, pending] — pending replaces useFormStatus in most cases
The form still uses action={formAction} — no onSubmit needed

📊 Production Insight

useActionState is the React 19 way to connect forms and Server Actions.

It provides state, the wrapped action, and pending status in one hook.

Rule: use useActionState for all new Next.js 16+ forms.

🎯 Key Takeaway

useActionState is the React 19 hook that connects forms to Server Actions.

It returns [state, formAction, pending] — pending tells you if the action is running.

The form uses action={formAction} — React handles submission automatically.

Dynamic Field Arrays: Invoice Line Items

Production forms often need dynamic fields — invoice line items, survey questions, team member invitations. React Hook Form's useFieldArray manages dynamic arrays with add, remove, and move operations. Combined with Zod's array schema, each item is validated independently.

The key pattern: the Zod schema defines an array of objects, useFieldArray manages the UI, and each array item is a FormField with its own validation. The total is computed from watched field values.

io.thecodeforge.forms.field-arrays.tsx · TSX

// ============================================
// Dynamic Field Arrays with useFieldArray
// ============================================

'use client'

import * as React from 'react'
import { useForm, useFieldArray, useWatch } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { invoiceSchema, type InvoiceFormValues } from '@/lib/schemas/invoice'
import { cn } from '@/lib/utils'
import {
  Form,
  FormControl,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from '@/components/ui/form'
import { Input } from '@/components/ui/input'
import { Button } from '@/components/ui/button'
import { Switch } from '@/components/ui/switch'

export function InvoiceForm() {
  const form = useForm<InvoiceFormValues>({
    resolver: zodResolver(invoiceSchema),
    defaultValues: {
      clientName: '',
      clientEmail: '',
      dueDate: '',
      items: [
        { description: '', quantity: 1, unitPrice: 0, taxable: false },
      ],
      notes: '',
      paymentTerms: 'net30',
    },
  })

  const { fields, append, remove } = useFieldArray({
    control: form.control,
    name: 'items',
  })

  const items = useWatch({ control: form.control, name: 'items' })

  const subtotal = items.reduce((sum, item) => {
    return sum + (item?.quantity || 0) * (item?.unitPrice || 0)
  }, 0)

  const taxTotal = items.reduce((sum, item) => {
    if (!item?.taxable) return sum
    return sum + (item?.quantity || 0) * (item?.unitPrice || 0) * 0.08
  }, 0)

  const total = subtotal + taxTotal

  async function onSubmit(data: InvoiceFormValues) {
    const response = await fetch('/api/invoices', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    })

    if (!response.ok) {
      const error = await response.json()
      if (error.fieldErrors) {
        Object.entries(error.fieldErrors).forEach(([field, message]) => {
          form.setError(field as any, {
            type: 'server',
            message: message as string,
          })
        })
      }
    }
  }

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-8">
        <div className="grid gap-4 md:grid-cols-2">
          <FormField
            control={form.control}
            name="clientName"
            render={({ field }) => (
              <FormItem>
                <FormLabel>Client Name</FormLabel>
                <FormControl>
                  <Input placeholder="Acme Corp" {...field} />
                </FormControl>
                <FormMessage />
              </FormItem>
            )}
          />
          <FormField
            control={form.control}
            name="clientEmail"
            render={({ field }) => (
              <FormItem>
                <FormLabel>Client Email</FormLabel>
                <FormControl>
                  <Input placeholder="billing@acme.com" {...field} />
                </FormControl>
                <FormMessage />
              </FormItem>
            )}
          />
        </div>

        <div className="space-y-4">
          <div className="flex items-center justify-between">
            <FormLabel className="text-base">Line Items</FormLabel>
            <Button
              type="button"
              variant="outline"
              size="sm"
              onClick={() =>
                append({
                  description: '',
                  quantity: 1,
                  unitPrice: 0,
                  taxable: false,
                })
              }
            >
              Add Item
            </Button>
          </div>

          {fields.map((field, index) => (
            <div
              key={field.id}
              className="grid gap-4 rounded-lg border p-4 md:grid-cols-5"
            >
              <FormField
                control={form.control}
                name={`items.${index}.description`}
                render={({ field }) => (
                  <FormItem className="md:col-span-2">
                    <FormLabel className={cn(index !== 0 && 'sr-only')}>
                      Description
                    </FormLabel>
                    <FormControl>
                      <Input placeholder="Service description" {...field} />
                    </FormControl>
                    <FormMessage />
                  </FormItem>
                )}
              />

              <FormField
                control={form.control}
                name={`items.${index}.quantity`}
                render={({ field }) => (
                  <FormItem>
                    <FormLabel className={cn(index !== 0 && 'sr-only')}>
                      Qty
                    </FormLabel>
                    <FormControl>
                      <Input
                        type="number"
                        min="1"
                        {...field}
                        onChange={(e) => field.onChange(e.target.valueAsNumber)}
                      />
                    </FormControl>
                    <FormMessage />
                  </FormItem>
                )}
              />

              <FormField
                control={form.control}
                name={`items.${index}.unitPrice`}
                render={({ field }) => (
                  <FormItem>
                    <FormLabel className={cn(index !== 0 && 'sr-only')}>
                      Price
                    </FormLabel>
                    <FormControl>
                      <Input
                        type="number"
                        step="0.01"
                        min="0"
                        {...field}
                        onChange={(e) => field.onChange(e.target.valueAsNumber)}
                      />
                    </FormControl>
                    <FormMessage />
                  </FormItem>
                )}
              />

              <div className="flex items-end gap-2">
                <FormField
                  control={form.control}
                  name={`items.${index}.taxable`}
                  render={({ field }) => (
                    <FormItem className="flex items-center gap-2">
                      <FormControl>
                        <Switch
                          checked={field.value}
                          onCheckedChange={field.onChange}
                        />
                      </FormControl>
                      <FormLabel className="text-xs">Tax</FormLabel>
                    </FormItem>
                  )}
                />
                {fields.length > 1 && (
                  <Button
                    type="button"
                    variant="ghost"
                    size="sm"
                    onClick={() => remove(index)}
                  >
                    Remove
                  </Button>
                )}
              </div>
            </div>
          ))}

          <div className="flex flex-col items-end gap-1 text-sm">
            <div className="flex w-48 justify-between">
              <span>Subtotal</span>
              <span>\${subtotal.toFixed(2)}</span>
            </div>
            <div className="flex w-48 justify-between">
              <span>Tax (8%)</span>
              <span>\${taxTotal.toFixed(2)}</span>
            </div>
            <div className="flex w-48 justify-between font-bold">
              <span>Total</span>
              <span>\${total.toFixed(2)}</span>
            </div>
          </div>
        </div>

        <Button
          type="submit"
          disabled={form.formState.isSubmitting}
          className="w-full"
        >
          {form.formState.isSubmitting ? 'Creating...' : 'Create Invoice'}
        </Button>
      </form>
    </Form>
  )
}

💡useFieldArray Patterns

Each field in the array has a unique id — use it as the React key, not the index
Use useWatch for computed values (totals) — not form.getValues() which does not trigger re-renders
Zod validates each array item independently — errors appear on the specific item's fields
append() adds a new item with default values — match the Zod schema's default shape
remove() takes an index — guard against removing the last item if the schema requires min 1

📊 Production Insight

useFieldArray generates unique ids for each item — use them as React keys, not array indexes.

useWatch triggers re-renders only for watched fields — use it for computed values like totals.

Rule: watch only fields that drive computed values — let React Hook Form handle the rest.

🎯 Key Takeaway

useFieldArray manages dynamic arrays — append, remove, move operations with unique ids.

Zod array schema validates each item independently — errors appear on specific fields.

useWatch for computed values (totals) — not form.getValues() which does not trigger re-renders.

Multi-Step Form Wizard with State Preservation

Multi-step forms split a large form into smaller sections, each on its own step. The challenge is preserving data across steps while validating incrementally. React Hook Form does not have built-in wizard support — the pattern uses a single form instance with conditional rendering based on the current step.

The key insight: do not create a separate form instance per step. Use one form, one schema, and validate only the current step's fields on step transition. The full schema validates on final submission.

io.thecodeforge.forms.multi-step.tsx · TSX

// ============================================
// Multi-Step Form Wizard
// ============================================

'use client'

import * as React from 'react'
import { useForm, useFormContext, FormProvider } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { z } from 'zod'
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
import { Label } from '@/components/ui/label'

// ---- Full schema — validated on final submit ----
const wizardSchema = z.object({
  firstName: z.string().min(2, 'First name is required'),
  lastName: z.string().min(2, 'Last name is required'),
  email: z.string().email('Invalid email'),

  street: z.string().min(1, 'Street is required'),
  city: z.string().min(1, 'City is required'),
  state: z.string().length(2, 'Use 2-letter code'),
  zip: z.string().regex(/^\d{5}$/, 'Invalid ZIP'),

  cardNumber: z.string().regex(/^\d{16}$/, 'Card must be 16 digits'),
  expiry: z.string().regex(/^\d{2}\/\d{2}$/, 'Format: MM/YY'),
  cvv: z.string().regex(/^\d{3,4}$/, 'CVV must be 3-4 digits'),
})

type WizardValues = z.infer<typeof wizardSchema>

// ---- Per-step validation schemas ----
const stepSchemas = [
  wizardSchema.pick({ firstName: true, lastName: true, email: true }),
  wizardSchema.pick({ street: true, city: true, state: true, zip: true }),
  wizardSchema.pick({ cardNumber: true, expiry: true, cvv: true }),
]

const steps = ['Personal Info', 'Address', 'Payment']

export function MultiStepForm() {
  const [currentStep, setCurrentStep] = React.useState(0)

  const form = useForm<WizardValues>({
    resolver: zodResolver(wizardSchema),
    defaultValues: {
      firstName: '',
      lastName: '',
      email: '',
      street: '',
      city: '',
      state: '',
      zip: '',
      cardNumber: '',
      expiry: '',
      cvv: '',
    },
    mode: 'onBlur',
  })

  async function nextStep() {
    const currentSchema = stepSchemas[currentStep]
    const currentFields = Object.keys(currentSchema.shape) as (keyof WizardValues)[]

    const isValid = await form.trigger(currentFields)

    if (isValid) {
      setCurrentStep((prev) => Math.min(prev + 1, steps.length - 1))
    }
  }

  function prevStep() {
    setCurrentStep((prev) => Math.max(prev - 1, 0))
  }

  async function onSubmit(data: WizardValues) {
    const response = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    })

    if (response.ok) {
      // Success
    }
  }

  return (
    <FormProvider {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
        <div className="flex items-center gap-2">
          {steps.map((step, index) => (
            <div
              key={step}
              className={`flex items-center gap-2 ${
                index <= currentStep ? 'text-primary' : 'text-muted-foreground'
              }`}
            >
              <span
                className={`flex h-8 w-8 items-center justify-center rounded-full border text-sm ${
                  index <= currentStep
                    ? 'border-primary bg-primary text-primary-foreground'
                    : 'border-muted'
                }`}
              >
                {index + 1}
              </span>
              <span className="text-sm font-medium">{step}</span>
              {index < steps.length - 1 && (
                <span className="text-muted-foreground">/</span>
              )}
            </div>
          ))}
        </div>

        {currentStep === 0 && <PersonalInfoStep />}
        {currentStep === 1 && <AddressStep />}
        {currentStep === 2 && <PaymentStep />}

        <div className="flex justify-between">
          <Button
            type="button"
            variant="outline"
            onClick={prevStep}
            disabled={currentStep === 0}
          >
            Previous
          </Button>

          {currentStep < steps.length - 1 ? (
            <Button type="button" onClick={nextStep}>
              Next
            </Button>
          ) : (
            <Button type="submit" disabled={form.formState.isSubmitting}>
              {form.formState.isSubmitting ? 'Processing...' : 'Submit'}
            </Button>
          )}
        </div>
      </form>
    </FormProvider>
  )
}

function PersonalInfoStep() {
  const { register, formState: { errors } } = useFormContext<WizardValues>()

  return (
    <div className="space-y-4">
      <div>
        <Label htmlFor="firstName">First Name</Label>
        <Input id="firstName" {...register('firstName')} />
        {errors.firstName && <p className="text-sm text-destructive">{errors.firstName.message}</p>}
      </div>
      {/* other fields */}
    </div>
  )
}

function AddressStep() {
  const { register, formState: { errors } } = useFormContext<WizardValues>()

  return (
    <div className="space-y-4">
      <div>
        <Label htmlFor="street">Street</Label>
        <Input id="street" {...register('street')} />
        {errors.street && <p className="text-sm text-destructive">{errors.street.message}</p>}
      </div>
      {/* other fields */}
    </div>
  )
}

function PaymentStep() {
  const { register, formState: { errors } } = useFormContext<WizardValues>()

  return (
    <div className="space-y-4">
      <div>
        <Label htmlFor="cardNumber">Card Number</Label>
        <Input id="cardNumber" {...register('cardNumber')} />
        {errors.cardNumber && <p className="text-sm text-destructive">{errors.cardNumber.message}</p>}
      </div>
      {/* other fields */}
    </div>
  )
}

⚠ Multi-Step Form Pitfalls

📊 Production Insight

One form instance for the entire wizard — separate instances lose data between steps.

Per-step validation uses schema.pick() — validate only the current step's fields on transition.

Rule: validate on step transition, full schema validates on final submit.

🎯 Key Takeaway

Multi-step forms use one form instance with conditional rendering — not separate forms per step.

Per-step validation with schema.pick() — validate current step fields on transition.

FormProvider + useFormContext shares the form instance across step components.

🗂 Form Approaches Compared

Performance, type safety, and complexity comparison

Approach	Re-Renders	Type Safety	Server Validation	Complexity	Best For
useState per field	Every keystroke	Manual types	Manual	Low	Simple forms, prototypes
React Hook Form	Minimal — uncontrolled	With z.infer	Manual	Medium	Production forms, complex UX
RHF + Zod + Server Action	Minimal — uncontrolled	Automatic from schema	Same schema	Medium-High	Full-stack type-safe forms
useActionState only	On server response	From action type	Built-in	Low	Simple server-only forms
Formik	Every keystroke	Manual types	Manual	Medium	Legacy projects (not recommended for new code)

🎯 Key Takeaways

Zod schema is the single source of truth — drives client validation, server validation, and TypeScript types
React Hook Form uses uncontrolled inputs — 90% fewer re-renders than useState-based forms
Server actions must re-validate with the same Zod schema — client validation is bypassable
z.infer<typeof schema> produces TypeScript types automatically — no manual type definitions
Use register for native inputs, Controller for custom components — mixing causes silent failures
safeParse returns { success, data, error } — never use parse() in server actions (it throws)

⚠ Common Mistakes to Avoid

✕Validating on client only — not re-validating on the server

Symptom

Bots bypass the browser and send invalid data directly to the API. Users with modified JavaScript can submit any data. The server accepts it because it trusts the client.

Fix

Import the same Zod schema in the server action and call schema.safeParse(data) before processing. Client validation is for UX — server validation is for security.

✕Using useState for form fields instead of React Hook Form

Symptom

Every keystroke triggers a re-render of the entire form component. Forms with 10+ fields become noticeably slow. React DevTools shows hundreds of re-renders per minute during typing.

Fix

Use React Hook Form with register for native inputs. It uses refs instead of state — typing does not trigger re-renders. The performance difference is 90% fewer re-renders.

✕Defining separate Zod schemas for client and server

Symptom

Client accepts data that the server rejects — or vice versa. Validation rules drift over time as developers update one schema but forget the other.

Fix

Define the Zod schema in a shared file (lib/schemas/). Import it on both the client (via zodResolver) and the server (via safeParse). One schema, two validation points.

✕Using register on shadcn/ui custom components

Symptom

The component does not respond to validation — errors do not display, the value is not tracked, form submission includes undefined for the field.

Fix

Use Controller or FormField for custom components (shadcn/ui Select, Checkbox, Switch). Use register only for native HTML inputs (input, textarea, select).

✕Not using useWatch for computed values in field arrays

Symptom

Invoice totals do not update as the user types — the values are stale because form.getValues() does not trigger re-renders.

Fix

Use useWatch({ control: form.control, name: 'items' }) to subscribe to field array changes. Recompute totals from the watched values — they update on every change.

✕Using z.parse() in server actions instead of z.safeParse()

Symptom

Server action throws an unhandled ZodError — the user sees a 500 error page instead of field-level validation errors.

Fix

Use safeParse() which returns { success, data, error } — never throws. Map the error.issues to field-level messages and return them to the client.

Interview Questions on This Topic

QHow does Zod, React Hook Form, and Next.js Server Actions work together to create type-safe forms?Mid-levelReveal
The three tools form a stack where Zod is the foundation: 1. Zod schema defines the validation rules and data shape. It is the single source of truth — imported by both client and server. 2. React Hook Form manages form state with uncontrolled inputs (refs, not state). zodResolver connects the Zod schema to React Hook Form's validation lifecycle. z.infer<typeof schema> produces the TypeScript type for the form values. 3. Next.js Server Actions receive FormData on the server. They import the same Zod schema and call safeParse() to validate before processing. If validation fails, they return field-level errors that the client displays. The result: one schema drives validation on both client and server, TypeScript types are inferred automatically, and the form has minimal re-renders because React Hook Form uses uncontrolled inputs.
QA form validates correctly in the browser but the server receives invalid data. What is happening and how do you fix it?SeniorReveal
This means either the client validation was bypassed (a bot sent raw HTTP requests) or the client and server Zod schemas have diverged. Diagnosis steps: 1. Check if the server action re-validates with Zod — if it trusts the request body without validation, that is the root cause. 2. Compare the client schema import path with the server schema import path — they should reference the same file. 3. Check if the schemas have diverged — add a field to the client schema but not the server schema (or vice versa). Fix: 1. Import the same Zod schema in the server action: import { signupSchema } from '@/lib/schemas/signup' 2. Call schema.safeParse(data) before processing — return field errors if validation fails. 3. Add a CI check that verifies the client and server import the same schema file. 4. Add rate limiting to the API route to prevent bot abuse. The fundamental rule: client validation is for UX (instant feedback), server validation is for security (prevents bypass). Both are required.
QWhat is the difference between register and Controller in React Hook Form?JuniorReveal
register returns props (name, onChange, onBlur, ref) that you spread on a native HTML input element. It uses the DOM's native change events and refs to track values — no React state involved. This is why it has minimal re-renders. Controller wraps a custom component and manages its value and change handler manually. It is required when the component does not accept standard input props — like shadcn/ui's Select, Checkbox, or Switch, which have their own onChange signatures (onValueChange, onCheckedChange). The rule: use register for native inputs (input, textarea, select HTML elements). Use Controller (or FormField in shadcn/ui) for custom components. Mixing them — trying to register a custom component — causes the value to not be tracked and validation to silently fail.
QHow would you build a multi-step form wizard with React Hook Form that validates incrementally?Mid-levelReveal
The pattern uses a single form instance with conditional rendering per step: 1. Define the full Zod schema with all fields from all steps. 2. Create per-step schemas using schema.pick() — each picks only the fields for that step. 3. Use one useForm instance — do not create separate forms per step. 4. On step transition, call form.trigger(stepFields) to validate only the current step's fields. If valid, advance. If invalid, show errors and stay. 5. On final submit, the full schema validates all fields — the user cannot skip step validation. 6. Use FormProvider to share the form context with step components. Each step uses useFormContext() to access register and formState. The key insight: one form, one schema, per-step validation on transition, full validation on submit. This preserves all data across steps and prevents skipping validation.

Frequently Asked Questions

Can I use Zod without React Hook Form?

Yes. Zod is a standalone validation library — it works with any form library or no form library at all. You can call schema.safeParse(data) in a plain function, a Server Action, or an API route. React Hook Form is optional — zodResolver is the bridge between them.

How do I handle file uploads with Zod and React Hook Form?

Zod can validate files with z.instanceof(File) or z.custom<File>(). React Hook Form handles file inputs via register — the File object is available in the form data. For Server Actions, use FormData directly (formData.get('file')) and validate the File object with Zod after extraction.

What is the difference between safeParse and parse in Zod?

parse() throws a ZodError if validation fails — you must wrap it in try/catch. safeParse() returns { success: true, data } or { success: false, error } — it never throws. In server actions, always use safeParse() to avoid unhandled exceptions that show 500 errors to users.

Can I use Yup instead of Zod with React Hook Form?

Yes — React Hook Form supports Yup via @hookform/resolvers/yup. However, Zod has better TypeScript integration (z.infer produces types automatically, Yup requires manual type definitions) and is more widely adopted in the Next.js ecosystem. For new projects, Zod is the recommended choice.

How do I test forms built with Zod and React Hook Form?

Test at two levels: unit test the Zod schema directly (schema.safeParse(validData) should pass, schema.safeParse(invalidData) should fail) and integration test the form with React Testing Library (fill fields, submit, assert errors appear). The schema tests are fast and do not require a DOM — run them in your CI pipeline.

🔥

Naren Founder & Author

Developer and founder of TheCodeForge. I built this site because I was tired of tutorials that explain what to type without explaining why it works. Every article here is written to make concepts actually click.

About Naren Get in touch

Forged with 🔥 at TheCodeForge.io — Where Developers Are Forged