Multistep-form-engine

Live demo

Try it live

A production-ready multi-step form template built for AI-assisted development. Designed to work with Bolt.new, Cursor, and other AI coding tools without breaking when you modify individual steps.

The problem this solves

AI code generators (Bolt, v0, Lovable) consistently break on complex multi-step forms. After 3-4 steps with validation and branching, the AI loses context, introduces bugs in unrelated steps, and burns through tokens fixing regressions.

This template solves that with strict file separation: each step is an isolated component. Modify one step, and nothing else breaks. The AI only needs to read and edit a single file.

What's included

• 5 form steps with diverse field types (text, email, select, radio, checkbox, file upload, textarea, switch toggle)
• Conditional branching: user answers determine which steps appear next
• Zod validation on every step with clear error messages
• Progress persistence: refreshing the page restores exactly where the user left off
• Review step: summary of all collected data with "edit" links back to specific steps
• Clickable progress bar: navigate to any completed step
• Mobile-responsive layout

Tech stack

React 18 · TypeScript · Vite · Tailwind CSS · shadcn/ui · React Hook Form · Zod · Zustand

Use cases

• SaaS user onboarding
• KYC / identity verification flows
• Insurance or loan applications
• Lead generation quizzes
• Product recommendation surveys
• Event registration with conditional fields

Quick start

Open in Bolt

Click "Import from GitHub" in Bolt.new and paste this repo URL. Start editing immediately — the claude.md file will guide the AI.

Local development

git clone https://github.com/[your-username]/multistep-form-engine.git
cd multistep-form-engine
npm install
npm run dev

How to customize

Add a new step

1. Create src/components/steps/StepYourName.tsx
2. Add the Zod schema to src/lib/schema.ts
3. Register the step in src/lib/form-store.ts
4. Update src/lib/branching.ts if the step is conditional

Change branching logic

Edit src/lib/branching.ts. Branching is a simple map — no step components need to change.

Upgrade to database persistence

Replace the localStorage middleware in form-store.ts with Supabase or any backend. The store interface stays the same.

File structure

src/
  components/
    FormShell.tsx            # Orchestrator (progress bar, navigation)
    ReviewStep.tsx           # Final review before submission
    steps/
      StepAccount.tsx        # Name, email, password
      StepProfile.tsx        # Company, role, team size
      StepGoals.tsx          # Business goals (conditional)
      StepTechnical.tsx      # Tech stack preferences (conditional)
      StepPreferences.tsx    # Notifications, timezone, avatar
  lib/
    schema.ts                # All Zod schemas (single source of truth)
    form-store.ts            # Zustand store with localStorage persistence
    branching.ts             # Step routing logic
  types/
    form.ts                  # Shared TypeScript types

Why this structure matters

AI coding tools work best when they can focus on one file at a time. This template enforces that pattern:

• Each step is isolated — no shared state between step components
• Validation is centralized — one file to update schemas
• Branching is declarative — a simple map, not scattered if/else statements
• The claude.md file in .bolt/ directory instructs AI tools on the project's rules and prevents common mistakes

License

MIT