Stepper
Last Updated: September 2026Steppers are visual cues that help users understand where they are in a journey. They communicate whats been completed, whats currently open, and what’s to come.
Source CodeAnatomy
link- 1Step icon
- 2Connector
- 3Label
- 4Subheading
Variants
linkHorizontal
Default orientation. Steps share row space with connectors.
Vertical
Stacks steps for narrow layouts or longer labels.
With error
status="error" on a step shows the danger treatment and error icon.
Custom icons
Override the default status icon via step.icon.
Usage Guidelines
linkWhen to use
- •To show progress through a known multi-step flow.
- •When users need orientation (where they are, what's next).
- •For wizards, onboarding, or claim submission sequences.
When not to use
- •For a single status chip — use DotStatus or Tag.
- •For indeterminate loading — use Spinner or Bar.
- •As a primary navigation tree — use Navigation patterns instead.
Keep exactly one active step; mark prior steps completed.
Don't mark multiple steps active — it breaks progress clarity.
Use vertical orientation when horizontal labels would truncate.
Don't use vague labels like Step 1 / Step 2 without meaning.
Behaviors
linksteps prop
- •Pass a steps array — Stepper is not a compound Root/Item API.
- •Each step: label (required), optional subheading, status, icon.
- •status defaults to pending when omitted.
Status icons
- •Defaults: completed→check, active→radio_button_checked, pending→radio_button_unchecked, error→error.
- •Override with step.icon when a custom glyph is clearer.
Connectors
- •Connectors follow the status of the step they leave (completed accent, error danger).
- •The last step has no connector.
Content Guidelines
linkLabels
- •Name the outcome of the step ('Coverage', not 'Continue').
- •Keep labels short; put detail in subheading.
- •Use synthetic demo names only — never real patient data.
Accessibility
linkText & Labels
- •Root list has aria-label="Progress" by default.
- •Labels and subheadings should be unique enough to scan.
ARIA attributes
- •Renders an ordered list (ol) of steps for list semantics.
- •Status meaning is also conveyed via icon and text color — keep labels accurate.
Keyboard Support
- •Stepper is not interactive; navigation belongs to surrounding UI.
WCAG Compliance Standards
FAQs
linkIs there a Stepper.Item compound API?
No — pass steps={[{ label, status, ... }]} to Stepper. There is no Root/Item composition.
How do I show a failed step?
Set status: "error" on that step. Prior steps should usually remain completed.
Horizontal vs vertical?
Horizontal is default for wide layouts. Vertical works better in sidebars and narrow columns.