Stepper / Wizard
Stepper (also called Wizard) breaks a complex multi-step process into clearly numbered steps with progress indication. It guides users through sequential tasks — setup flows, onboarding, checkout, and multi-step forms.
When to Use
Use Stepper when
- Multi-step form with 3-7 logical sections
- Onboarding or setup wizard
- Sequential process where order matters
- User needs progress feedback on long tasks
Don't use Stepper when
- Only 1-2 steps — use a modal form instead
- Steps are non-sequential (any order) — use Tabs
- More than 7 steps — reconsider the UX
Anatomy
1
Step indicator
Numbered circle. pending: gray bg. active: #6366F1 + glow ring. completed: #0E9F6E + checkmark. 32px diameter.
2
Connector line
Horizontal line between steps. Color: #E2E8F0 (pending) → #6366F1 (completed). Top: 16px (center of 32px dot).
3
Step label
11px fw-600. Below the dot. Truncates at ~80px width. Color matches step state.
4
Content area
White card below stepper. Changes content per active step. Consistent padding: 24px.
5
Navigation footer
Back (outline, left) + Next/Submit (primary, right) buttons. Step counter in center.
Variants
Account
2
Details
3
Review
4
Complete
Step 2 of 4 — Details
Fill in the details for this step. Content changes per active step.
States
3
Pending
bg:#F1F5F9, color:#94A3B8
2
Active
bg:#6366F1, white number, glow ring
Completed
bg:#0E9F6E, white checkmark
4
Disabled
opacity:.4, not clickable
Properties
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
| steps | array | required | — | Array of {label, content}. 3-7 items recommended. |
| currentStep | number | required | 0 | Zero-indexed active step number. |
| onNext | function | required | — | Called when Next button is clicked. Validate current step before advancing. |
| onBack | function | required | — | Called when Back button is clicked. Back is disabled on step 0. |
| onSubmit | function | required | — | Called on last step when Next becomes Submit. |
| allowSkip | boolean | optional | false | When true, users can click completed step dots to jump back. |
Behavior
| Trigger | Behavior |
|---|---|
| Next click | Validate current step fields first. If valid: mark current as completed, advance to next step, scroll to top of content. |
| Back click | Go to previous step. Previous step remains completed (not reset). Back is disabled on step 0. |
| Last step Submit | Next button label changes to "Submit". Click fires onSubmit. Show loading state while submitting. |
| Completed dot click | If allowSkip:true, clicking a completed step navigates back to it. Clears completion of all subsequent steps. |
Accessibility
| Requirement | Implementation |
|---|---|
| Step list | Use <ol> for step indicators. Each step is <li>. |
| Current step | Add aria-current="step" to the active step indicator. |
| Progress | Add aria-label="Step 2 of 4" to the stepper container. |
| Content region | Add aria-live="polite" to content area so screen readers announce step changes. |
Composition
Allowed
Full page layout for setup/onboarding
Inside a large modal (modal-lg)
Form fields inside each step content panel
Forbidden
Nested steppers
More than 7 steps
Non-sequential processes (use Tabs)
Best Practices
Do
Validate each step before advancing. Show inline errors in the current step — never on the next step.
Errors caught early prevent frustration at submission time.
Don't
Allow users to skip ahead to future steps without completing current ones.
Future steps may depend on data from previous steps. Skipping breaks data integrity.
Content Rules
Good step labels
Account / Details / Review / Done
Short nouns (1-2 words). Each describes the category of data on that step.
Bad step labels
Step 1 / Step 2 / Step 3
Generic numbers give no context about what each step contains.
AI Implementation Guide
For AI coding assistants: Stepper has 3 zones: indicator row (dots + connectors), content panel (current step), navigation footer (Back / counter / Next). Step dots: 32px circles — pending:gray, active:#6366F1+glow, completed:#0E9F6E+checkmark. Connector lines use CSS ::after on each step. Last step: Next becomes "Submit". Back disabled on step 0. Always validate current step before calling onNext. Show loading state on Submit.
Related Components
Design Decisions
Why show completed steps as green (#0E9F6E) instead of keeping them primary (#6366F1)?
Green = done. It uses the success semantic color to communicate "this is finished and correct". Keeping completed steps purple would create ambiguity with the active step. The green checkmark communicates completion clearly without users having to count steps or read labels.
Why connector lines change color as steps complete?
The line between step 1 (completed, green) and step 2 (active, purple) should be green — it connects two completed/active states. Color-filling the connector as steps complete provides a visual "progress bar" effect across the entire stepper width, reinforcing the sense of forward movement.
Changelog
v1.0.0July 2026Added
- Initial release — pending/active/completed states, connector lines, Back/Next/Submit navigation
- allowSkip mode for clicking completed steps
- aria-live on content area for screen reader announcements