Multi-Step Form Wrapper

A flexible multi-step form component that guides users through complex forms with step-by-step validation, progress tracking, and auto-save functionality.

Overview

The Multi-Step Form Wrapper component breaks down complex forms into manageable steps, providing clear navigation, validation at each step, and features like auto-save and progress tracking. Perfect for onboarding flows, surveys, and detailed data collection.

Installation

npm

npx shadcn@latest add https://rigidui.com/r/multi-step-form-wrapper.json

Usage

Preview

import { MultiStepFormWrapper, Step } from "@/components/multi-step-form-wrapper"

export default function MyComponent() {
  return (
    <MultiStepFormWrapper>
      <Step title="Basic Info">
        <FormBasic />
      </Step>
      <Step title="Message">
        <FormMessage />
      </Step>
    </MultiStepFormWrapper>
  )
}

Code

import { MultiStepFormWrapper, Step, useMultiStepForm } from "@/components/multi-step-form-wrapper"
import { z } from "zod"

const userSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
  message: z.string().min(10)
})

function StepOne() {
  const { form, updateFormData } = useMultiStepForm()
  
  return (
    <div className="space-y-4">
      <input {...form.register("name")} placeholder="Name" />
      <input {...form.register("email")} placeholder="Email" />
    </div>
  )
}

function StepTwo() {
  const { form } = useMultiStepForm()
  
  return (
    <textarea {...form.register("message")} placeholder="Message" />
  )
}

export default function MyForm() {
  const handleComplete = (data) => {
    console.log('Form completed:', data)
  }

  return (
    <MultiStepFormWrapper
      schema={userSchema}
      onComplete={handleComplete}
      showProgressBar
      autoSave
      persistKey="user-form"
    >
      <Step title="Personal Info" description="Tell us about yourself">
        <StepOne />
      </Step>
      <Step title="Your Message" description="What would you like to say?">
        <StepTwo />
      </Step>
    </MultiStepFormWrapper>
  )
}

Features

Step-by-Step Flow

Guide users through complex forms with a clear step-by-step interface and visual progress tracking.

Zod Validation

Comprehensive step-by-step validation with Zod schemas, custom error messages, and validation error callbacks.

Auto-Save & Persistence

Automatically save form progress to localStorage with configurable debouncing and persistent form state.

Smooth Animations

Beautiful step transitions with configurable animation duration and seamless user experience.

Flexible Configuration

Highly customizable with step lifecycle hooks, optional steps, progress bars, and accessibility features.

TypeScript Support

Full TypeScript support with type inference and comprehensive type definitions.

API Reference

MultiStepFormWrapper

The main container component that manages multi-step form state and navigation.

children · React.ReactNode · required

Step components to render within the form.

onComplete · (data: FormData) => void

Callback function called when the form is completed.

initialData · Record<string, unknown> · default: "{}"

Initial data for the form.

schema · ZodSchema

Zod schema for overall form validation.

className · string

Additional class names for styling.

showStepIndicator · boolean · default: "true"

Whether to show the step indicator.

showStepTitle · boolean · default: "true"

Whether to show the step title and description.

showProgressBar · boolean · default: "false"

Whether to show progress bar with percentage.

allowSkipSteps · boolean · default: "false"

Whether to allow skipping to other steps.

navigationPosition · 'bottom' | 'top' · default: "'bottom'"

Position of the navigation buttons.

nextButtonText · string · default: "'Next'"

Text for the next button.

prevButtonText · string · default: "'Back'"

Text for the previous button.

completeButtonText · string · default: "'Complete'"

Text for the complete button.

allowStepReset · boolean · default: "false"

Whether to show a reset button to go back to first step.

onStepChange · (prevStep: number, nextStep: number) => void

Callback function called when the step changes.

onStepValidationError · (step: number, errors: FieldErrors) => void

Callback function called when step validation fails.

persistKey · string

Key for localStorage persistence of form data.

autoSave · boolean · default: "false"

Whether to automatically save form data to localStorage.

autoSaveDelay · number · default: "1000"

Delay in milliseconds for auto-save debouncing.

animateStepChange · boolean · default: "true"

Whether to animate step transitions.

transitionDuration · number · default: "300"

Duration of step transition animations in milliseconds.

Step

Defines an individual step in the multi-step form.

children · React.ReactNode · required

Content to render in this step.

title · string

Title displayed for this step.

description · string

Description displayed below the title.

validate · (data: T) => Promise<boolean> | boolean

Custom validation function for this step.

schema · z.ZodObject<any>

Zod schema for step-specific validation.

canSkip · boolean · default: "false"

Whether this step can be skipped without validation.

isOptional · boolean · default: "false"

Whether this step is optional.

validationMessage · string

Custom error message shown when validation fails.

onEnter · (data: T) => void

Callback when entering this step.

onExit · (data: T) => void

Callback when exiting this step.

TypeScript Interfaces

MultiStepFormContextType

interface MultiStepFormContextType<T extends FormData = FormData> {
  currentStep: number
  totalSteps: number
  formData: T
  updateFormData: (stepData: Partial<T>) => void
  goToNextStep: () => Promise<void>
  goToPrevStep: () => void
  goToStep: (step: number) => void
  resetForm: () => void
  isFirstStep: boolean
  isLastStep: boolean
  isComplete: boolean
  isLoading: boolean
  form: UseFormReturn<T>
  getProgressPercentage: () => number
  stepErrors: Record<number, string>
}

StepProps

interface StepProps<T extends FormData = FormData> {
  children: React.ReactNode
  title?: string
  description?: string
  validate?: (data: T) => Promise<boolean> | boolean
  schema?: z.ZodObject<any>
  canSkip?: boolean
  isOptional?: boolean
  validationMessage?: string
  onEnter?: (data: T) => void
  onExit?: (data: T) => void
}

Use the useMultiStepForm hook within your step components to access form state and methods like updateFormData, currentStep, and the React Hook Form instance.

Combine step-level schemas with the overall form schema for comprehensive validation. Step schemas validate individual steps, while the main schema validates the complete form data.

When using localStorage persistence with persistKey, ensure you handle data migration if your form schema changes between versions.