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.

  1. Details

    Completed

  2. Preferences

    Current step

  3. Review

    Upcoming

HTML
<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.

  1. Address

    Completed

  2. Shipping

    Current step

  3. Confirmation

    Upcoming

HTML
<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.

  1. Account

    Completed

  2. Profile

    Current step · Error: check the supplied details

  3. Notifications

    Upcoming · Optional

  4. Finish

    Upcoming

HTML
<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-completed and .is-error as needed.
  • Keep .stepper-item directly inside the list, with .stepper-marker and .stepper-content directly inside each item. Labels and status text may use wrappers inside the content; .is-error colors both through the existing text tokens.
  • Place nested .stepper lists 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.

TokenDefaultPurposeScope / state
--stepper-gapvar(--spacer-3)Space between a marker and its content; also clears horizontal connectors..stepper
--stepper-item-gapvar(--spacer-4)Vertical spacing after a step and horizontal content end spacing..stepper
--stepper-marker-size2.25remMarker width and height..stepper
--stepper-marker-font-sizevar(--font-size-sm)Number, checkmark and error icon size..stepper
--stepper-colorvar(--text-color)Text and icon color; error content uses var(--stepper-error-bg)..stepper; .stepper-item.is-error > .stepper-content
--stepper-muted-colorvar(--text-muted)Status text color; error content uses var(--stepper-error-bg)..stepper; .stepper-item.is-error > .stepper-content
--stepper-bgvar(--bg-surface)Default marker background..stepper
--stepper-border-colorvar(--control-border-color)Default marker border color..stepper
--stepper-connector-colorvar(--border-color)Line color between steps..stepper
--stepper-connector-width0.1875remConnector thickness..stepper
--stepper-current-bgvar(--primary)Current marker background, border and ring color..stepper
--stepper-current-colorvar(--on-primary)Current marker foreground..stepper
--stepper-current-surfacevar(--bg-highlight)Declared token; currently not consumed by the component styles..stepper
--stepper-current-ring-size0.1875remCurrent marker ring thickness and offset..stepper
--stepper-completed-bgvar(--success)Completed marker and outgoing connector color..stepper
--stepper-completed-colorvar(--on-success)Completed marker foreground..stepper
--stepper-error-bgvar(--error)Error marker background, border, label and status text color..stepper
--stepper-error-colorvar(--on-error)Error marker foreground..stepper
--stepper-content-paddingvar(--spacer-3)Top padding for start-aligned horizontal step content..stepper
--stepper-content-radiusvar(--border-radius)Declared token; currently not consumed by the component styles..stepper