Stepper
Ordered progress with current, completed, optional and error states.
When to use
Use a stepper to show progress through a multi-step task such as checkout or onboarding. Use a Timeline for a chronological history rather than task completion.
Horizontal
Add .stepper-horizontal for a directional horizontal layout from md; smaller screens stack vertically.
- Details
Completed
- Preferences
Current step
- Review
Upcoming
<ol class="stepper stepper-horizontal" role="list" aria-label="Setup progress">
<li class="stepper-item is-completed">
<span class="stepper-marker" aria-hidden="true">1</span>
<div class="stepper-content">
<strong class="stepper-label">Details</strong>
<p class="stepper-status">Completed</p>
</div>
</li>
<li class="stepper-item" aria-current="step">
<span class="stepper-marker" aria-hidden="true">2</span>
<div class="stepper-content">
<strong class="stepper-label">Preferences</strong>
<p class="stepper-status">Current step</p>
</div>
</li>
<li class="stepper-item">
<span class="stepper-marker" aria-hidden="true">3</span>
<div class="stepper-content">
<strong class="stepper-label">Review</strong>
<p class="stepper-status">Upcoming</p>
</div>
</li>
</ol>Start-aligned horizontal
Add .stepper-align-start with .stepper-horizontal to align every marker and label to the logical start of its equal-width column. It keeps the vertical layout below md and follows the document direction in RTL.
- Address
Completed
- Shipping
Current step
- Confirmation
Upcoming
<ol
class="stepper stepper-horizontal stepper-align-start"
role="list"
aria-label="Delivery progress">
<li class="stepper-item is-completed">
<span class="stepper-marker" aria-hidden="true">1</span>
<div class="stepper-content">
<strong class="stepper-label">Address</strong>
<p class="stepper-status">Completed</p>
</div>
</li>
<li class="stepper-item" aria-current="step">
<span class="stepper-marker" aria-hidden="true">2</span>
<div class="stepper-content">
<strong class="stepper-label">Shipping</strong>
<p class="stepper-status">Current step</p>
</div>
</li>
<li class="stepper-item">
<span class="stepper-marker" aria-hidden="true">3</span>
<div class="stepper-content">
<strong class="stepper-label">Confirmation</strong>
<p class="stepper-status">Upcoming</p>
</div>
</li>
</ol>Vertical states
The base layout is vertical. Visible state text avoids color-only meaning.
- Account
Completed
- Profile
Current step · Error: check the supplied details
- Notifications
Upcoming · Optional
- Finish
Upcoming
<ol class="stepper" role="list" aria-label="Form progress">
<li class="stepper-item is-completed">
<span class="stepper-marker" aria-hidden="true">1</span>
<div class="stepper-content">
<strong class="stepper-label">Account</strong>
<p class="stepper-status">Completed</p>
</div>
</li>
<li class="stepper-item is-error" aria-current="step">
<span class="stepper-marker" aria-hidden="true">2</span>
<div class="stepper-content">
<strong class="stepper-label">Profile</strong>
<p class="stepper-status">Current step · Error: check the supplied details</p>
</div>
</li>
<li class="stepper-item">
<span class="stepper-marker" aria-hidden="true">3</span>
<div class="stepper-content">
<strong class="stepper-label">Notifications</strong>
<p class="stepper-status">Upcoming · Optional</p>
</div>
</li>
</ol>Accessibility and behavior
- Use an accessibly named ordered list.
- Use
aria-current="step",.is-completedand.is-erroras needed. - Keep
.stepper-itemdirectly inside the list, with.stepper-markerand.stepper-contentdirectly inside each item. Labels and status text may use wrappers inside the content;.is-errorcolors both through the existing text tokens. - Place nested
.stepperlists inside.stepper-content; each list keeps its own orientation, alignment and states. - Keep status text visible; markers are decorative.
- Use links or buttons only for navigable steps.
Applications manage state, validation and focus. See Checkout and Onboarding.
CSS variables
Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.
| Token | Default | Purpose | Scope / state |
|---|---|---|---|
--stepper-gap | var(--spacer-3) | Space between a marker and its content; also clears horizontal connectors. | .stepper |
--stepper-item-gap | var(--spacer-4) | Vertical spacing after a step and horizontal content end spacing. | .stepper |
--stepper-marker-size | 2.25rem | Marker width and height. | .stepper |
--stepper-marker-font-size | var(--font-size-sm) | Number, checkmark and error icon size. | .stepper |
--stepper-color | var(--text-color) | Text and icon color; error content uses var(--stepper-error-bg). | .stepper; .stepper-item.is-error > .stepper-content |
--stepper-muted-color | var(--text-muted) | Status text color; error content uses var(--stepper-error-bg). | .stepper; .stepper-item.is-error > .stepper-content |
--stepper-bg | var(--bg-surface) | Default marker background. | .stepper |
--stepper-border-color | var(--control-border-color) | Default marker border color. | .stepper |
--stepper-connector-color | var(--border-color) | Line color between steps. | .stepper |
--stepper-connector-width | 0.1875rem | Connector thickness. | .stepper |
--stepper-current-bg | var(--primary) | Current marker background, border and ring color. | .stepper |
--stepper-current-color | var(--on-primary) | Current marker foreground. | .stepper |
--stepper-current-surface | var(--bg-highlight) | Declared token; currently not consumed by the component styles. | .stepper |
--stepper-current-ring-size | 0.1875rem | Current marker ring thickness and offset. | .stepper |
--stepper-completed-bg | var(--success) | Completed marker and outgoing connector color. | .stepper |
--stepper-completed-color | var(--on-success) | Completed marker foreground. | .stepper |
--stepper-error-bg | var(--error) | Error marker background, border, label and status text color. | .stepper |
--stepper-error-color | var(--on-error) | Error marker foreground. | .stepper |
--stepper-content-padding | var(--spacer-3) | Top padding for start-aligned horizontal step content. | .stepper |
--stepper-content-radius | var(--border-radius) | Declared token; currently not consumed by the component styles. | .stepper |