Home / Primitives / Stepper

Stepper

The visual indicator at the top of a multi-step flow. Shows the user how far they are, what is done, and what is left — without ever stealing focus from the form.

New .p-stepper 3 step states · 2 layouts

Usage

Use one stepper per wizard. Place it directly under the page or sheet title so the user reads "where am I" before reading "what to do".

Step 2 of 4 .p-stepper · .p-step

Step states

Three states map directly to the wizard reducer: done for already-validated steps, current for the visible step, pending for the rest.

Done

.p-step.done

Current

.p-step.current

Pending

.p-step.pending

Layouts

The compact pill row is the default — quietest, works on phone widths. The labelled variant prints each step name on desktop wizards where horizontal space allows.

Compact (default) .p-stepper

01Type 02Dates 03Cover 04Review

Labelled .p-stepper.p-stepper--labelled

Parts

Property	Value	Notes
height (compact)	6px	Pill bar
gap	4px	Between segments
radius	3px	Pill bar · 8px on labelled cells
state colours	--brand · --surface-muted	done/current = brand · pending = surface
transition	--dur-fast (120ms)	background + border
role	progressbar	aria-valuenow / aria-valuemax

Do & don't

Let the user JUMP backwards to a completed step. Clicking a .done segment is the cheapest "let me change my earlier answer".

Don't

Let the user JUMP forward past a .pending segment. That's what the Next button is for — and it runs validation.

Show 3–5 steps. More than 5 and the visual rhythm breaks; consider grouping into sub-flows.

Don't

Use a stepper for a single-page form. Wizard UX has overhead; only pay it when the flow truly needs splitting.

Code

<!-- Compact, step 2 of 4 -->
<div class="p-stepper" role="progressbar"
     aria-valuenow="2" aria-valuemin="1" aria-valuemax="4">
  <span class="p-step done"></span>
  <span class="p-step current"></span>
  <span class="p-step pending"></span>
  <span class="p-step pending"></span>
</div>

<!-- Labelled layout -->
<div class="p-stepper p-stepper--labelled">
  <button class="p-step done">01 Type</button>
  <button class="p-step current" aria-current="step">02 Dates</button>
  <button class="p-step pending" disabled>03 Cover</button>
  <button class="p-step pending" disabled>04 Review</button>
</div>

For the full multi-step flow including reducer, validation, and "save & resume", see the Multi-step wizard recipe in the cookbook.