How to Add a Multi-Step Form Wizard to Your App (Copy-Paste Prompts Included)

Use a separate useForm() with a step-specific zod schema for each step component. When the user clicks Next, call form.handleSubmit() which triggers zod validation for the current step's fields only. If validation passes, the handleSubmit callback receives the validated data — call your onStepComplete(data) prop to pass it to the parent orchestrator, then advance currentStep. If validation fails, react-hook-form automatically sets form.formState.errors and the Next button stays on the current step. Never use a single useForm() for the entire wizard — it prevents isolated per-step validation and causes back-navigation data loss.

Write formData to localStorage on every change using a useEffect that watches the formData state. Use a namespaced, versioned key like 'wizard_onboarding_v1'. On component mount, a separate useEffect (empty dependency array, runs once on client) reads from localStorage and calls setFormData to pre-fill all steps. In Next.js, never read localStorage during render or in useState's initializer — this causes SSR hydration mismatches. Clear the localStorage key after successful submission so returning users start fresh.

Build a StepIndicator component that receives currentStep (0-indexed) and totalSteps. Render a row of numbered circles: index < currentStep is 'completed' (show a check icon), index === currentStep is 'active' (accent color), index > currentStep is 'upcoming' (outlined). On mobile widths under 768px, replace the full stepper with a simple 'Step {currentStep + 1} of {totalSteps}' text element — a 5-step horizontal stepper with labels overflows on phones. shadcn/ui has a Steps component, or you can build a simple custom implementation in under 30 lines.

Yes — this is the central architecture decision. Each step component must receive its previously entered values as defaultValues from the parent orchestrator's formData object. When the user clicks Next, the step calls onStepComplete(form.getValues()) to merge its values back into the parent. When the user clicks Back and the step re-mounts, it receives defaultValues={formData.step1} and pre-fills with the saved values. If back navigation clears the form, the step is reading from its own internal state instead of the parent's formData.

Use Framer Motion's AnimatePresence with mode='wait' wrapping the active step. Each step is wrapped in a motion.div with key={currentStep}. Track a direction state ('forward' | 'back') in the orchestrator — set it before changing currentStep. Forward: new step slides in from the right (initial: x: '100%'); back: new step slides in from the left (initial: x: '-100%'). The exit animation is the reverse. Set the transition to 200ms ease-in-out. Without mode='wait', both steps are in the DOM simultaneously during the transition, causing react-hook-form to register duplicate field names.

Accumulate all step data in a parent-level formData object as users complete each step. Only on the final step's Submit button click, validate the entire formData with a combined zod schema (the intersection or merge of all step schemas) and send it to Supabase as a single insert or to a Next.js Server Action. This approach avoids abandoned partial records and keeps submission handling simple. Store the complete formData as a JSONB column (step_data) alongside a form_type column in the wizard_submissions table.

Give each step its own useForm() initialized with a step-specific zod schema via zodResolver. This means the zod schema for step 1 only validates step 1 fields — email, name — and the step 2 schema only validates step 2 fields — address, city, state. When the user clicks Next, trigger validation for the current step only; errors appear inline under the relevant fields. On the final Submit, re-validate the entire combined payload before writing to the database using a merged schema that includes all step schemas. This prevents a step from being 'completed' with invalid data that the user thought was valid.

For most wizards, save only on final submission and use localStorage for in-progress state. Saving to the database between steps creates abandoned partial records from users who never complete the wizard — at 10,000 users these quickly pollute your submissions table and complicate GDPR data retention. The exception is when authenticated users explicitly need cross-device resume (start on mobile, finish on desktop). In that case, upsert to a separate wizard_drafts table after each step and move to wizard_submissions atomically on final submission. Run a cleanup job to delete drafts older than 30 days.