Multi-step formPro
A guided form that presents one decision at a time and preserves progress.
Pattern · live
- Onboarding or intake flows split into a few short steps.
- Wizards that need Back and Continue, progress, and a success state out of the box.
- Use stepper when you only need the progress indicator.
- Use checkout-flow or project-intake for full page flows.
- Use onboarding-checklist for tasks done outside a form.
Installation
Pro source and install commands unlock with a Pro plan.
Usage
Use it when a form needs distinct steps. Keep the number of steps small and provide a clear completion action.
example.tsx
import { MultiStepForm } from "@/registry/components/multi-step-form/multi-step-form"; export function Onboarding() { return ( <MultiStepForm steps={[ { id: "account", title: "Account", content: <AccountFields /> }, { id: "team", title: "Team", description: "Who will you work with?", content: <TeamFields /> }, { id: "plan", title: "Plan", content: <PlanFields /> }, ]} onComplete={saveOnboarding} /> );}API reference
2 parts. The first is the root.
MultiStepForm
A wizard that shows one fieldset per step with a progress list, Back and Continue actions, and a success state after the last step.
PropTypeDefaultDescription
stepsRequiredFormStep[]–Steps in order. Renders nothing when empty.onComplete() => void–Called when the last step is submitted.nextLabelstring"Continue"Submit label on every step except the last.completeLabelstring"Finish"Submit label on the last step.initialStepnumber0Zero-based starting step, clamped to the range.FormStep
Step type: { id: string; title: string; description?: string; content: ReactNode }. title becomes the fieldset legend and the progress label.
No props.
- Enter
- Submits the step (native form submit), advancing or finishing.
- Tab
- Moves through step fields and the Back and Continue buttons.
- Each step is a fieldset with a legend, and focus moves to the new legend (or the success heading) after navigation.
- Progress is a labelled nav with aria-current=step, plus a visually hidden aria-live line announcing Step 2 of 3.
- The success state is role=status. Native required and pattern constraints in step content block submit before the step advances.
- Steps slide 20px in the direction of travel while the shell springs to the new step's height.
- Completed markers draw a check, the step count rolls, and the submit button's width springs when the label changes.
- Reduced motion swaps steps, heights, and labels instantly.
- The progress list scrolls horizontally when steps overflow.
- Below 420px the progress header stacks with the step count on top and padding tightens.
- Only the active step is rendered, so keep field values in parent state.
- The shell springs to each step's height; step content is otherwise untouched.
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
- Use for onboarding or intake flows split into a few short steps. Use stepper for a standalone progress indicator and checkout-flow or project-intake for full page flows.
- Step content is rendered only while active, so keep field values in parent state; validation beyond native constraints is up to you.
The full library index for assistants is at /llms.txt.