` and the step count is
0, no nav bar renders and nothing is navigable.
- **`readonly` is a different thing from `nav="false"` and from `disabled`.**
`nav="false"` only hides the Back / Continue bar; every header stays a button,
so a trail built that way still invites a click that does nothing. `disabled`
says "you may not", which is a refusal, and it dims the step to 0.38 —
wrong for a stage that simply has not happened yet. `readonly` says there was
never an action: the header drops `role="button"`, its tab stop, its ripple
and its state layer, keeps `aria-current` so a reader still learns which stage
is live, and keeps every step at full contrast. It also makes `mode`
irrelevant, because nothing is navigating: linear gating no longer dims the
stages ahead. A step you explicitly mark `disabled` stays disabled.
- `active` clamps into `0 … count - 1` (and to `0` when there are no steps),
including the initial attribute value.
- **`mdBeforeChange` is the validation hook.** It fires for step clicks, the
built-in Back / Continue, and `next()` / `prev()` / `goTo()`. Cancel it to
keep the user where they are.
- **Assigning `active` yourself does not emit `mdBeforeChange`** — it still
emits `mdStepChange` and still applies auto-complete. That is the sanctioned
way to commit a transition you vetoed while you awaited something. Never call
`next()` or `goTo()` from inside a handler that cancelled `mdBeforeChange`:
they re-emit it and re-enter your handler.
- `auto-complete` (default **on**) moving **forward** marks every non-disabled
step you passed over as `completed` and clears its `error`. Moving
**backward** it un-completes the target and everything after it, so a later
step can never stay checked while an earlier one is not — unless the target
is `editable` **and** already `completed`, which is review-in-place and
leaves downstream completion alone.
- `next()` on the last reachable step does not move: with `auto-complete` on it
marks the current step completed, then emits `mdComplete`. `next()` and
`prev()` skip `disabled` steps.
- `mode="linear"` gating: backward is always allowed; forward is allowed only
when the target is already `completed`, or every earlier step is `completed`
or `optional`. Unreachable step headers are `aria-disabled` and out of the
tab order. `mode="non-linear"` allows any non-disabled step.
- **`next-disabled` and `loading` gate only the built-in Continue button.**
Clicking a step header and calling `next()` / `goTo()` are unaffected — use
`mode="linear"` and/or `mdBeforeChange` for those. `loading` also disables
Back, which is what stops a double-submit.
- **Where the nav lives depends on orientation.** A horizontal stepper renders
one Back / Continue bar below the content; a vertical stepper has each active
step render its own Back / Continue inside its panel. Both are suppressed by
`nav="false"`, and a vertical step opts out individually with `hide-actions`.
- `variant="mobile"` hides the entire step-header row and renders the compact
Back · progress · Continue bar instead, so the active panel must go in the
stepper's `content` slot. That bar is part of the navigation: with
`nav="false"` nothing is rendered but the content slot.
- `lazy` mounts only the active step's panel; the others are out of layout and
out of the a11y tree, with no collapse animation. It drops the *panel*, not
your component — slotted custom elements stay connected in the light DOM, so
a real teardown means conditionally rendering the content in your framework.
- **Panels live in one of two places, and the stepper picks the layout.** Put
content inside each `md-step` and it panels per step — expanding in place when
vertical, spanning the full width under the row when horizontal. Put one
`
` on the stepper instead and you own a single region you
swap on `mdStepChange`.
- **Per-step panels are detected, not configured.** There is no prop: the moment
any step has light-DOM content, a horizontal stepper switches its row from a
flex line to a grid so the panel can span every column underneath. A
horizontal stepper whose steps are all empty is unaffected.
This is why two placements exist at all — a slot cannot reach a *grandchild*,
so `md-stepper` can never project a step's children into its own `content`
region. Only `md-step` can render them, and the grid is what lets its panel
escape a `flex: 1 1 0` column that would otherwise be 1/N of the row.
- The built-in buttons are internal chrome: their composed `mdClick` retargets
to the stepper's host and is stopped there, so a delegated listener on any
ancestor never sees Back or Continue. `stopPropagation()` does not silence
listeners bound to the `
` element itself — those still fire for
the built-in buttons, so don't delegate off the host. Listen for
`mdStepChange` / `mdComplete` instead.
---
## Do / Don't
House rules, informed by
[M3 · Progress indicators](https://m3.material.io/components/progress-indicators/guidelines)
and [M3 · Tabs](https://m3.material.io/components/tabs/guidelines).
| ✅ Do | ❌ Don't |
|---|---|
| Use a stepper only for genuinely sequential work | Don't use one for peer views — that's tabs |
| Validate in `mdBeforeChange` and cancel on failure | Don't let users advance past an invalid step silently |
| Keep step labels to one or two words | Don't write sentences as step labels |
| Mark genuinely skippable steps `optional` | Don't mark everything optional |
| Show errors on the step with `error` + `error-text` | Don't surface step errors only in a dialog |
| Localize every `*-word` and `*-label` | Don't ship the English defaults |
| Use `mode="non-linear"` when order really doesn't matter | Don't force linear order artificially |
| Keep the step count small (3–5) | Don't build a twelve-step wizard |
| Use `loading` for async transitions | Don't leave the user unsure whether Continue worked |
| Put the panel inside each step when it belongs to that step | Don't hand-roll a `content` slot and swapping code you don't need |
---
## Patterns
```html
Account fields go here.
Payment fields go here.
Summary goes here.
```
```html
Email field goes here.
Profile fields go here.
```
```html
All set.
```
```html
Name your workspace.
Invite teammates.
Review and finish.
```
```html
Welcome!
```
```html
First.
Second.
Back
Continue
```
```html
Champs du compte.
Champs de paiement.
```
## Anti-patterns
| ❌ Wrong | ✅ Right | Why |
|---|---|---|
| Wrapping the steps in a `