form-validation

name	form-validation
description	React Hook Form + Zod integration, multi-step forms, optimistic validation, server-side error mapping, and file upload patterns.

Form Validation

React Hook Form + Zod patterns for robust, accessible forms.

React Hook Form + Zod Setup

// Install: npm install react-hook-form zod @hookform/resolvers

import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { z } from 'zod'

// 1. Define schema
const TaskSchema = z.object({
  title:       z.string().min(1, 'Title is required').max(200),
  description: z.string().max(2000).optional(),
  priority:    z.enum(['low', 'medium', 'high']),
  dueDate:     z.string().date('Invalid date').optional(),
})

type TaskFormData = z.infer<typeof TaskSchema>

// 2. Use in component
export function TaskForm({ onSubmit }: { onSubmit: (data: TaskFormData) => Promise<void> }) {
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting, isDirty },
    setError,
    reset,
  } = useForm<TaskFormData>({
    resolver: zodResolver(TaskSchema),
    defaultValues: { priority: 'medium' },
  })

  const submit = handleSubmit(async (data) => {
    try {
      await onSubmit(data)
      reset()
    } catch (err) {
      // Map server errors to fields (see Server-Side Error Mapping)
      setError('title', { message: 'A task with this title already exists' })
    }
  })

  return (
    <form onSubmit={submit} noValidate>
      <div>
        <label htmlFor="title">Title *</label>
        <input
          id="title"
          {...register('title')}
          aria-invalid={!!errors.title}
          aria-describedby={errors.title ? 'title-error' : undefined}
        />
        {errors.title && (
          <p id="title-error" role="alert" className="text-red-600 text-sm">
            {errors.title.message}
          </p>
        )}
      </div>

      <button type="submit" disabled={isSubmitting || !isDirty}>
        {isSubmitting ? 'Saving...' : 'Save Task'}
      </button>
    </form>
  )
}

Form Schema Definition with Zod

import { z } from 'zod'

// Common field patterns
const emailField = z.string().email('Invalid email address').toLowerCase()
const passwordField = z.string()
  .min(8, 'At least 8 characters')
  .regex(/[A-Z]/, 'Must contain uppercase letter')
  .regex(/[0-9]/, 'Must contain a number')

const urlField = z.string().url('Must be a valid URL').optional().or(z.literal(''))

const phoneField = z.string()
  .regex(/^\+?[1-9]\d{1,14}$/, 'Invalid phone number')
  .optional()

// Cross-field validation (refine)
const PasswordChangeSchema = z
  .object({
    password:        passwordField,
    confirmPassword: z.string(),
  })
  .refine(data => data.password === data.confirmPassword, {
    message: 'Passwords do not match',
    : [],   
  })


  = z
  .({
    :      z.([, ]),
    :       z.().().(),
    :   z.().(),
  })
  .( {
     (data. ===  && !data.) {
      ctx.({ : , : , : [] })
    }
     (data. ===  && !data.) {
      ctx.({ : , : , : [] })
    }
  })

Multi-Step Form State Management

import { useState } from 'react'
import { useForm, FormProvider } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'

const steps = ['Personal', 'Details', 'Review'] as const
type Step = (typeof steps)[number]

// Each step has its own schema
const Step1Schema = z.object({ name: z.string().min(1), email: emailField })
const Step2Schema = z.object({ company: z.string().min(1), role: z.string().min(1) })
const FullSchema = Step1Schema.merge(Step2Schema)

type FormData = z.infer<typeof FullSchema>

export function MultiStepForm() {
   [currentStep, setCurrentStep] = ()

   methods = useForm<>({
    : (),
    : ,
  })

   stepSchemas = [, ]

    =  () => {
    
     fieldsToValidate = .(stepSchemas[currentStep].)  (keyof )[]
     valid =  methods.(fieldsToValidate)
     (valid) ( s + )
  }

   submit = methods.( (data) => {
     (data)
  })

   (
    
  )
}

Server-Side Validation Error Mapping

import { useForm } from 'react-hook-form'

// API returns: { errors: { field: string[] } }
interface ApiError {
  errors?: Record<string, string[]>
  message?: string
}

export function RegistrationForm() {
  const { register, handleSubmit, setError, formState: { errors } } = useForm<FormData>()

  const submit = handleSubmit(async (data) => {
    try {
      await registerUser(data)
    } catch (err) {
      const apiError = err as ApiError

      if (apiError.errors) {
        // Map each server field error to react-hook-form
        Object.entries(apiError.errors).forEach(([field, messages]) => {
          setError(field as keyof FormData, {
            type: 'server',
            message: messages[0],
          })
        })
      } else {
        // Non-field error — show at form root
        setError(, { : apiError. ??  })
      }
    }
  })

   (
    
  )
}

Optimistic Validation (Real-time Feedback)

import { useForm } from 'react-hook-form'
import { useCallback } from 'react'
import { useDebouncedCallback } from 'use-debounce'

export function UsernameField() {
  const { register, setError, clearErrors, formState: { errors } } = useForm()

  const checkUsername = useDebouncedCallback(async (username: string) => {
    if (username.length < 3) return
    try {
      const available = await fetch(`/api/check-username?u=${username}`)
        .then(r => r.json())
        .then(d => d.available)

      if (!available) {
        setError('username', { message: `"${username}" is already taken` })
      } else {
        clearErrors('username')
      }
    } catch {
      // network error — don't block the form
    }
  }, )

   (
    
  )
}

File Upload with Preview

import { useForm, Controller } from 'react-hook-form'
import { useState, useCallback } from 'react'

const UploadSchema = z.object({
  avatar: z
    .instanceof(File)
    .refine(f => f.size < 5 * 1024 * 1024, 'Max 5 MB')
    .refine(f => ['image/jpeg', 'image/png', 'image/webp'].includes(f.type), 'JPEG, PNG or WebP only'),
})

export function AvatarUpload() {
  const { control, handleSubmit } = useForm<z.infer<typeof UploadSchema>>({
    resolver: zodResolver(UploadSchema),
  })
  const [preview, setPreview] = useState<string | null>(null)

  return (
    <form onSubmit={handleSubmit(async ({ avatar }) => {
      const fd = new FormData()
      fd.append('avatar', avatar)
      await fetch('/api/avatar', { method: 'POST', body: fd })
    })}>
       (
          
             {
                const file = e.target.files?.[0]
                if (!file) return
                field.onChange(file)
                setPreview(URL.createObjectURL(file))
              }}
            />
            {preview && }
            {fieldState.error && {fieldState.error.message}}
          
        )}
      />
      Upload
    
  )
}

Dynamic Form Fields (Arrays, Conditional)

import { useForm, useFieldArray, useWatch } from 'react-hook-form'

const LinksSchema = z.object({
  links: z.array(z.object({
    url:   z.string().url('Invalid URL'),
    label: z.string().min(1),
  })).min(1),
  hasExpiry: z.boolean(),
  expiryDate: z.string().optional(),
}).superRefine((data, ctx) => {
  if (data.hasExpiry && !data.expiryDate) {
    ctx.addIssue({ code: 'custom', message: 'Expiry date required', path: ['expiryDate'] })
  }
})

export function LinksForm() {
  const { register, control, handleSubmit, formState: { errors } } = useForm({
    resolver: zodResolver(LinksSchema),
    defaultValues: { links: [{ url: '', :  }], :  },
  })

   { fields, append, remove } = ({ control, :  })
   hasExpiry = ({ control, :  })

   (
    
  )
}

Form Submission States

type FormStatus = 'idle' | 'submitting' | 'success' | 'error'

export function ContactForm() {
  const [status, setStatus] = useState<FormStatus>('idle')
  const { register, handleSubmit, reset } = useForm()

  const submit = handleSubmit(async (data) => {
    setStatus('submitting')
    try {
      await sendMessage(data)
      setStatus('success')
      reset()
      setTimeout(() => setStatus('idle'), 3000)
    } catch {
      setStatus('error')
    }
  })

  return (
    <form onSubmit={submit}>
      {/* fields */}
      {status === 'success' && (
        <div role="status" className="text-green-600">Message sent!</div>
      )}
      {status === 'error' && (
        <div role="alert" =>Failed to send. Try again.
      )}
      
        {status === 'submitting' ? 'Sending...' : 'Send'}
      
    
  )
}