Stepper

Anatomy

A stepper is a row or column of steps. Each step has a marker (a Coin showing a number, an icon, a status glyph, or a bare dot), a label — beneath the marker when horizontal, beside it when vertical — and a connecting line to the next step. A line turns green only between two completed steps, so the green run shows what has actually been finished.

Guidelines

Use Stepper as the progress indicator at the top of a wizard or any flow broken into a fixed, ordered set of steps — where knowing "which step am I on, and how many are left" helps someone complete the task.

Do not use Stepper for navigation between unrelated views (use Tabs), for a checklist of independent tasks that can be done in any order over time, or for a single-step form. If sequence does not matter, it is not a stepper.

Best practices

Keep the number of steps small — roughly three to six. Long flows overwhelm; consider grouping sub-steps or splitting the task.

Mark exactly one step isCurrent — the stage whose content is on screen.

Set status="complete" on steps the customer has finished, so the green line and checks reflect real progress. Marking a step current is not a claim that the steps before it are done — if a flow lets people jump ahead, the lines behind them stay grey until those steps are genuinely complete. Use isDisabled only for steps genuinely gated on earlier ones; if a step can be revisited, leave it enabled.

Flag a step critical when it holds errors that block finishing the flow, and caution when it needs a look but doesn't block. Treat these markers as a pointer to where the problem is, never as the problem statement: the step's own inline field errors, and any summary on a review step, remain the message. A flagged marker with nothing explaining it on the step itself leaves someone with nowhere to go.

Make flagged steps reachable. Flagging a step someone cannot navigate to tells them there is a problem and then blocks them from fixing it.

Don't flag steps speculatively — a step is only critical or caution once something on it has actually been evaluated. Flagging every unvisited step turns the whole indicator red and the signal into noise.

Make steps navigable with href when each maps to a route, so people can jump back to completed steps. Disabled steps are inert automatically — don't rely on visual styling alone to prevent navigation.

Keep the current-step affordance meaningful: the bold label and filled marker should always point at where the customer actually is.

Types

content="number" (default) numbers each step — best when the sequence and step count matter, and when steps are referenced by number elsewhere (docs, support).

content="icon" shows a per-step icon — good for short flows (2–3 steps) where the sequence is less important than what each step is about. Completed steps still show a check.

content="minimal" shows bare dots with no numbers or labels — the lightest treatment, for read-only or quick click-through flows where the stepper's visual weight should match the little content it carries. Don't use it when a step needs to be referred to by name or number, and don't use it for a flow where a step's status carries weight: minimal markers drop the check and the attention icons too, so states differ only by the coin's color. Reach for number or icon there.

status="critical" and status="caution" are the two attention states, and the choice between them is whether the flow can still be completed. Red is for a step whose errors block completion or submission; yellow is for a step that needs review or attention but lets someone carry on. If they can still press the final button, it is caution.

Appearance

Steps use semantic, non-decorative color: green marks completed steps and the finished stretches of line between them, an accent-colored ring marks the current step — drawn around the marker whatever the marker's own state colored it — red marks a critical step and yellow a caution one, and neutral grey marks upcoming and disabled steps as well as every line that isn't between two completed steps. Don't recolor these to arbitrary palette colors — the meaning is in the semantics, not the hue.

Neither attention status is carried by color alone, and the two are not separated by hue alone. critical shows the circled exclamation Pluma pairs with its red semantic and caution the triangle it pairs with yellow, so the shapes differ too, and each marker carries visually-hidden text ("has errors", "needs attention") for assistive technology. Keep that intact if you override the marker colors. The shapes are the one part content="minimal" drops — see Types.

A step can be flagged and current at once — the ordinary case of coming back to fix something. The status keeps the marker's fill and the current step's ring sits outside the coin rather than replacing its edge, so both read at once without either color contradicting the other. The connecting lines are unaffected: an attention step is not a completed one, so the green run keeps meaning only "this stretch is done".

Use size (sm, md, lg) to match the surrounding density; default to md. Don't invent new marker sizes or line weights.

Use layout="fill" (default) when the stepper heads a full-width flow, so the steps spread across the available width. Use layout="fit" when it should be a compact, centered indicator inside a wider container — it hugs its content with a consistent step width instead of stretching. layout only affects the horizontal orientation.

Use orientation="horizontal" (default) for the progress indicator across the top of a wizard. Use orientation="vertical" when the stepper sits in a sidebar or rail beside the flow, or when a long form is chunked into stages down the page — the steps stack in a column with each label beside its marker. The states, colors, and fill behavior are identical to horizontal; only the axis changes.

Behaviors

Stepper renders as an ordered list (<ol>) of steps (<li>), so assistive technology reads them in sequence. The current step is exposed with aria-current="step".

When a step has an href or onClick, its whole marker-and-label area becomes one link or button. Disabled steps render inert (no navigation, no click) through PlainLink.

Markers and the connecting line are decorative; a step's meaning comes from its visible label (or, in minimal steppers, its accessible name). The exception is the two attention statuses, which add visually-hidden text to the step so they are announced rather than being left to the marker's color.

Content

Write labels as short, one- to two-word nouns for the stage — Recipients, Goal, Schedule, Review. Avoid verbs and sentences; the label is a signpost, not an instruction. Keep labels parallel in form across the steps.