Skip to main content

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

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

Usage

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>
  )
}

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.

Build docs developers (and LLMs) love