Stepper
A Stepper component is used to show a list of steps in a linear manner. Use the interactive preview below to click “Next Step” or “Previous” to see the state transitions.
Loading Code Block...Full example
Section titled “Full example”A vertical stepper with three labelled steps. Use the buttons below to advance through them; the default arrangement is 'vertical' in both frameworks.
Loading Code Block...Arrangement
Section titled “Arrangement”Use the `arrangement` prop to toggle between a vertical or horizontal layout. You can try this out using the dropdown below.
Loading Code Block...Per-step custom content (vertical only)
Section titled “Per-step custom content (vertical only)”The vertical arrangement supports replacing the default title/subtext block with arbitrary content on a per-step basis. The horizontal arrangement only renders step.title and ignores any custom-content escape hatch in either framework.
In React, set slot on a VerticalStep to a ReactNode. When provided, it replaces the entire title/subtext block for that step.
In Vue, declare a per-id scoped slot named ${step.id}-content. The slot scope receives { step, stepIdx, isCompleted, isCurrent, isError, isWarning, isAlert } so you can branch on per-step state.
Loading Code Block...Stepper
Section titled “Stepper”| Props | Default | Type | Description |
|---|---|---|---|
| steps* | - | BaseStep[] | VerticalStep[] | Array of step objects (see `BaseStep` / `VerticalStep` below). The horizontal arrangement uses `BaseStep[]`; the vertical arrangement also accepts `VerticalStep[]` so each step can render custom content. |
| currentStep* | - | number | 1-based index of the active step. Steps before it render as completed, the matching step renders as current, and the rest render as upcoming. |
| arrangement | 'vertical' | 'vertical' | 'horizontal' | Layout orientation. Omitting the prop renders a vertical stepper in both frameworks. |
| size | 'default' | 'default' | 'sm' | Controls the step circle/text scale. Applies to both vertical and horizontal arrangements. |
| variant | 'default' | 'default' | 'dot' | Visual style for the active step indicator. `'dot'` replaces the step number with a small filled circle; completed steps still render the check icon. |
BaseStep / VerticalStep
Section titled “BaseStep / VerticalStep”| Props | Default | Type | Description |
|---|---|---|---|
| id* | - | string | Stable identifier used as the React `key` for the step (and, in Vue, as the prefix for the per-step `${id}-content` named slot). Must be unique within `steps`. |
| title* | - | string | Step label rendered next to the circle (vertical) or beneath it (horizontal). |
| subtext | - | string | Supporting line shown below the title in the vertical arrangement. Ignored on the horizontal arrangement. |
| status | - | 'error' | 'warning' | 'alert' | Status badge applied when the step is the current or a completed step. Drives both the circle styling and the trailing connector colour. |
| onClick | - | () => void | Optional click handler wired to the per-step container. |
| slot | - | ReactNode | Custom content that replaces the default title/subtext block on a vertical step. Not part of `BaseStep`, so the horizontal arrangement does not accept it. |
Accessibility
Section titled “Accessibility”- The stepper uses semantically appropriate roles (
listandlistitem) to help screen readers announce the number of steps and the current position. - Progress indicators use visually hidden text or robust ARIA traits so visually impaired users can differentiate between ‘completed’, ‘current’, and ‘upcoming’ steps.
- Color contrast is carefully maintained between active states and faded out future steps so they are clearly determinable.