form-handling

Form Handling — React Hook Form + Zod

When to Use This Skill

Activate this skill when:

• Building any form (login, registration, settings, checkout)
• Adding client-side or server-side validation
• Building multi-step wizards or survey flows
• Handling file uploads with validation
• Integrating forms with Next.js server actions
• Working with dynamic/repeating field groups (invoices, line items)

---

Stack

pnpm add react-hook-form zod @hookform/resolvers

Package	Purpose
react-hook-form	Performant form state management with uncontrolled inputs
zod	TypeScript-first schema validation with type inference
@hookform/resolvers	Bridges Zod schemas to React Hook Form validation

---

1. Basic Typed Form Pattern

Define the schema once with Zod, infer the TypeScript type, and pass it to useForm. This eliminates type duplication between validation and form state.

// schemas/contact.ts
import { z } from "zod";

export const contactSchema = z.object({
  name: z
    .string()
    .min(2, "Name must be at least 2 characters")
    .max(100, "Name must be under 100 characters"),
  email: z
    .string()
    .email("Please enter a valid email address"),
  message: z
    .string()
    .min(10, "Message must be at least 10 characters")
    .max(1000, "Message must be under 1000 characters"),
});

export type ContactFormData = z.infer<typeof contactSchema>;

// components/ContactForm.tsx
"use client";

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { contactSchema, type ContactFormData } from "@/schemas/contact";

export function ContactForm() {
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting },
    reset,
  } = useForm<ContactFormData>({
    resolver: zodResolver(contactSchema),
    defaultValues: {
      name: "",
      email: "",
      message: "",
    },
  });

  async function onSubmit(data: ContactFormData) {
    // data is fully typed and validated at this point
    const response = await fetch("/api/contact", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data),
    });

    if (response.ok) {
      reset();
    }
  }

  return (
    <form onSubmit={handleSubmit(onSubmit)} noValidate>
      <FormField
        label="Name"
        error={errors.name?.message}
      >
        <input
          {...register("name")}
          type="text"
          aria-invalid={!!errors.name}
          aria-describedby={errors.name ? "name-error" : undefined}
        />
      </FormField>

      <FormField
        label="Email"
        error={errors.email?.message}
      >
        <input
          {...register("email")}
          type="email"
          aria-invalid={!!errors.email}
          aria-describedby={errors.email ? "email-error" : undefined}
        />
      </FormField>

      <FormField
        label="Message"
        error={errors.message?.message}
      >
        <textarea
          {...register("message")}
          rows={4}
          aria-invalid={!!errors.message}
          aria-describedby={errors.message ? "message-error" : undefined}
        />
      </FormField>

      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? "Sending..." : "Send Message"}
      </button>
    </form>
  );
}