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 >
)
}
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
The main container component that manages multi-step form state and navigation.
Step components to render within the form.
Callback function called when the form is completed.
initialData
Record<string, unknown>
default: "{}"
Initial data for the form.
Zod schema for overall form validation.
Additional class names for styling.
Whether to show the step indicator.
Whether to show the step title and description.
Whether to show progress bar with percentage.
Whether to allow skipping to other steps.
navigationPosition
'bottom' | 'top'
default: "'bottom'"
Position of the navigation buttons.
Text for the next button.
Text for the previous button.
completeButtonText
string
default: "'Complete'"
Text for the complete button.
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.
Key for localStorage persistence of form data.
Whether to automatically save form data to localStorage.
Delay in milliseconds for auto-save debouncing.
Whether to animate step transitions.
Duration of step transition animations in milliseconds.
Step
Defines an individual step in the multi-step form.
Content to render in this step.
Title displayed for this step.
Description displayed below the title.
validate
(data: T) => Promise<boolean> | boolean
Custom validation function for this step.
Zod schema for step-specific validation.
Whether this step can be skipped without validation.
Whether this step is optional.
Custom error message shown when validation fails.
Callback when entering this step.
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.