Multi-Step Wizard Flow

Architecture

lib/types.ts          → WIZARD_STEPS constant + WizardStep union
lib/store.ts          → Zustand + persist (localStorage)
components/wizard/
  wizard-shell.tsx    → renders current step component
  step-indicator.tsx  → progress UI
  wizard-nav.tsx      → Back / Next / Skip
  steps/*.tsx         → one component per step

Step registry

Single source of truth — never hardcode step numbers in multiple files:

export type WizardStep = "intro" | "profile" | "settings" | "review";

export const WIZARD_STEPS: WizardStep[] = [
  "intro",
  "profile",
  "settings",
  "review",
];

Display number = WIZARD_STEPS.indexOf(step) + 1.

Zustand store essentials

interface WizardStore {
  currentStep: WizardStep;
  data: AppData;
  setCurrentStep: (step: WizardStep) => void;
  nextStep: () => void;
  prevStep: () => void;
  reset: () => void;
}

// Navigation
nextStep: () => {
  const idx = WIZARD_STEPS.indexOf(get().currentStep);
  if (idx < WIZARD_STEPS.length - 1) set({ currentStep: WIZARD_STEPS[idx + 1] });
},

Persist + migrate

persist(store, {
  name: "app-wizard",
  merge: (persisted, current) => {
    const p = persisted as Partial<WizardStore>;
    return {
      ...current,
      ...p,
      currentStep: migrateStep(p.currentStep), // handle renamed/removed steps
      data: normalizeData(p.data ?? current.data),
    };
  },
});

migrateStep: if step not in WIZARD_STEPS, fall back to first valid step.

Step indicator

Two modes:

1. Expanded: dot per step, index + 1 label, click to jump (only to completed steps)
2. Grouped: collapse related steps (e.g. Start / Profile / Finances)

const STEP_GROUPS = [
  { label: "Start", steps: ["intro"] as WizardStep[] },
  { label: "Profile", steps: ["profile"] as WizardStep[] },
  { label: "Finish", steps: ["settings", "review"] as WizardStep[] },
];

Group is active when currentStep is in group; complete when all group steps visited.

Intro step overview cards

If step 1 is intro, overview cards show upcoming sections — not step 1 itself:

Keep card step labels derived from WIZARD_STEPS indices, not hand-maintained offsets.

WizardNav component

interface WizardNavProps {
  showBack?: boolean;
  onNext?: () => void;
  onBack?: () => void;
  nextLabel?: string;
  nextDisabled?: boolean;
  showSkip?: boolean;
  onSkip?: () => void;
}

Per-step validation: pass nextDisabled until required fields valid.

Step component contract

Each step:

• Reads/writes store slices (not prop drilling entire tree)
• Calls nextStep / prevStep via WizardNav
• Optional steps: show Skip → still advances
• No route changes per step (single /wizard page) unless SEO requires URLs

URL sync (optional)

For shareable progress: ?step=profile synced via useSearchParams + router.replace. Validate against WIZARD_STEPS.

Analytics hooks

Fire on step enter and completion:

trackEvent("wizard_step_view", { step: currentStep, step_index: idx + 1 });
trackEvent("wizard_complete", { total_steps: WIZARD_STEPS.length });

UX checklist

- [ ] Back preserves entered data (persist handles this)
- [ ] Intro explains sections with correct step numbers
- [ ] Review step shows read-only summary before submit
- [ ] Reset clears storage and returns to intro
- [ ] Mobile: indicator scrolls horizontally if many steps

Pair with: zustand-persist-state, react-hooks-patterns, specialized-form-inputs.

Anti-patterns

• Duplicating step order in intro cards, indicator, and store separately
• Using React Router steps when a single page + store is simpler
• Losing data on refresh without persist/middleware