How to Use
SteppedForm
SteppedForm breaks a long form into sequential steps, each with its own fields and validation. Users navigate forward and backward between steps, and can only proceed when the current step's validation passes. The component handles step navigation, progress indication, and collects all field values across all steps into a single object on final submit. Use it for signup wizards, checkout flows, multi-page surveys, and setup wizards.
Multi-Step Wizard
Define steps as an array of objects, each with a title and fields array. Each field mirrors FormFieldSet's API: type, name, label, validation, options, etc. The SteppedForm renders step indicators at the top, the current step's fields in the middle, and Previous/Next/Submit buttons at the bottom. Each step validates independently — users cannot proceed until the current fields pass validation. On the final step, onSubmit fires with all fields combined into a single object.
const steps = [
{ title: "Account", fields: [{ type: "email", name: "email", label: "Email", validation: { rules: { required: true, email: true } } }] },
{ title: "Profile", fields: [{ type: "text", name: "name", label: "Full Name", validation: { rules: { required: true } } }] },
{ title: "Confirm", fields: [{ type: "switch", name: "terms", label: "I accept the terms", validation: { rules: { required: true } } }] },
];
<SteppedForm steps={steps} onSubmit={(data) => console.log(data)} />Props Reference
All available props for SteppedForm. See the full API reference page for interactive playground examples.
| Prop | Type | Default | Description |
|---|---|---|---|
| steps | SteppedFormStep[] | — | Array of step definitions (required). |
| initialStep | number | 0 | Start at this step index. |
| onStepChange | (index: number) => void | — | Called on step navigation. |
| headerVariant | "numbers" | "circles" | "progress" | "numbers" | Step header style. |
| disableHeaderNavigation | boolean | false | Prevent clicking step headers. |
| backLabel | ReactNode | "Back" | Back button label. |
| nextLabel | ReactNode | "Next" | Next button label. |
| submitLabel | ReactNode | "Submit" | Submit button label. |
| classNames | { base?: string; header?: string; body?: string; footer?: string } | — | Slot class overrides. |
Best Practices
- ◆Each step validates independently — the user cannot proceed if the current step has errors
- ◆Use descriptive step titles so users understand their progress through the flow
- ◆SteppedForm works best with 3-5 steps — more than 5 can feel overwhelming
- ◆The onSubmit callback receives all fields from all steps as a single flat object keyed by field name
- ◆Fields across steps must have unique names — duplicate names will be overwritten in the final data object
- ◆Progress is automatically tracked — the component shows which step is active, completed, and upcoming