Correct and idiomatic ways to use the <mds-stepper-bar> component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in agents/conventions.md.

Minimal Stepper with Step Labels

The canonical form. Place <mds-stepper-bar-item> elements in the default slot, one per step. Every item requires icon and label; badge and step enable the status badge and step counter visuals. Set items-done to control which step is active - 1 activates the first step.

<mds-stepper-bar items-done="1">
  <mds-stepper-bar-item
    badge
    step
    icon="mi/baseline/person"
    icon-checked="mi/baseline/done"
    label="Dati account"
  ></mds-stepper-bar-item>
  <mds-stepper-bar-item
    badge
    step
    icon="mi/baseline/badge"
    icon-checked="mi/baseline/done"
    label="Dati personali"
  ></mds-stepper-bar-item>
  <mds-stepper-bar-item
    badge
    step
    icon="mi/baseline/lock-open"
    icon-checked="mi/baseline/done"
    label="Attivazione"
  ></mds-stepper-bar-item>
</mds-stepper-bar>

Advancing Steps Programmatically

Drive progress by updating items-done from outside. itemsDone = 0 leaves all items pending; itemsDone = N + 1 (where N is the total number of items) marks the whole flow as complete. Do not mutate the children’s done or current attributes directly - only the parent controls those.

<mds-stepper-bar id="reg-stepper" items-done="1">
  <mds-stepper-bar-item badge step icon="mi/baseline/person" icon-checked="mi/baseline/done" label="Account"></mds-stepper-bar-item>
  <mds-stepper-bar-item badge step icon="mi/baseline/badge" icon-checked="mi/baseline/done" label="Profilo"></mds-stepper-bar-item>
  <mds-stepper-bar-item badge step icon="mi/baseline/done" icon-checked="mi/baseline/done" label="Conferma"></mds-stepper-bar-item>
</mds-stepper-bar>

<mds-button label="Prossimo" variant="primary" tone="strong" id="btn-next"></mds-button>

<script>
  let step = 1;
  document.getElementById('btn-next').addEventListener('click', () => {
    step += 1;
    document.getElementById('reg-stepper').setAttribute('items-done', String(step));
  });
</script>

Listening to the Change Event

React to step changes via mdsStepperBarChange. The event detail carries step (zero-based index of the current item) and value (comma-joined value attributes of all completed items).

<mds-stepper-bar id="wizard" items-done="1">
  <mds-stepper-bar-item value="account" badge step icon="mi/baseline/person" icon-checked="mi/baseline/done" label="Account"></mds-stepper-bar-item>
  <mds-stepper-bar-item value="profilo" badge step icon="mi/baseline/badge" icon-checked="mi/baseline/done" label="Profilo"></mds-stepper-bar-item>
  <mds-stepper-bar-item value="conferma" badge step icon="mi/baseline/done" icon-checked="mi/baseline/done" label="Conferma"></mds-stepper-bar-item>
</mds-stepper-bar>

<script>
  document.getElementById('wizard').addEventListener('mdsStepperBarChange', (e) => {
    console.log('Step corrente:', e.detail.step);
    console.log('Passi completati:', e.detail.value); // es. "account,profilo"
  });
</script>

Content Panels Synchronized with Steps

Add elements with slot="content" - one per step in the same order as the items. The component hides all panels except the one matching the active step, by adding the hidden class: the page needs a .hidden { display: none } rule (the Tailwind utility provides it). Nest navigation buttons inside each panel to let users move forward and back.

<mds-stepper-bar items-done="1">
  <mds-stepper-bar-item badge step icon="mi/baseline/person" icon-checked="mi/baseline/done" label="Account"></mds-stepper-bar-item>
  <mds-stepper-bar-item badge step icon="mi/baseline/badge" icon-checked="mi/baseline/done" label="Profilo"></mds-stepper-bar-item>

  <div slot="content">
    <mds-text>Inserisci i dati del tuo account.</mds-text>
    <mds-button
      label="Prossimo"
      variant="primary"
      tone="strong"
      onclick="document.querySelector('mds-stepper-bar').setAttribute('items-done', '2')"
    ></mds-button>
  </div>

  <div slot="content">
    <mds-text>Completa il tuo profilo.</mds-text>
    <mds-button
      label="Indietro"
      variant="dark"
      tone="outline"
      onclick="document.querySelector('mds-stepper-bar').setAttribute('items-done', '1')"
    ></mds-button>
    <mds-button
      label="Conferma"
      variant="primary"
      tone="strong"
      onclick="document.querySelector('mds-stepper-bar').setAttribute('items-done', '3')"
    ></mds-button>
  </div>
</mds-stepper-bar>

Scrollbar Navigation for Long Flows

For flows with many steps, set navigation="scrollbar" to expose a styled horizontal scrollbar under the indicator track. The active item scrolls into view automatically; the scrollbar appearance is configurable through the --mds-stepper-bar-scrollbar-* custom properties.

<mds-stepper-bar items-done="1" navigation="scrollbar">
  <mds-stepper-bar-item badge step icon="mi/baseline/person" icon-checked="mi/baseline/done" label="Account"></mds-stepper-bar-item>
  <mds-stepper-bar-item badge step icon="mi/baseline/badge" icon-checked="mi/baseline/done" label="Dati personali"></mds-stepper-bar-item>
  <mds-stepper-bar-item badge step icon="mi/round/email" icon-checked="mi/baseline/done" label="Newsletter"></mds-stepper-bar-item>
  <mds-stepper-bar-item badge step icon="mi/baseline/lock-open" icon-checked="mi/baseline/done" label="Attivazione"></mds-stepper-bar-item>
  <mds-stepper-bar-item badge step icon="mi/baseline/login" icon-checked="mi/baseline/done" label="Accedi"></mds-stepper-bar-item>
  <mds-stepper-bar-item badge step icon="mi/baseline/done" icon-checked="mi/baseline/done" label="Completato"></mds-stepper-bar-item>
</mds-stepper-bar>

Offset Margin inside a Padded Container

When the stepper bar lives inside a padded card or panel, use --mds-stepper-bar-offset-margin to let the indicator track bleed into the padding without altering the outer container’s spacing.

.wizard-card mds-stepper-bar {
  --mds-stepper-bar-offset-margin: 24px;
}

<div class="wizard-card" style="padding: 24px;">
  <mds-stepper-bar items-done="2">
    <mds-stepper-bar-item badge step icon="mi/baseline/person" icon-checked="mi/baseline/done" label="Account"></mds-stepper-bar-item>
    <mds-stepper-bar-item badge step icon="mi/baseline/badge" icon-checked="mi/baseline/done" label="Profilo"></mds-stepper-bar-item>
    <mds-stepper-bar-item badge step icon="mi/baseline/done" icon-checked="mi/baseline/done" label="Conferma"></mds-stepper-bar-item>
  </mds-stepper-bar>
</div>

Styling the Scrollbar and Gap

Style the indicator track’s scrollbar and item spacing through the documented --mds-stepper-bar-* CSS custom properties. Use semantic color roles via rgb(var(--magma-<role>)) so dark mode and high-contrast keep working.

mds-stepper-bar {
  --mds-stepper-bar-gap: calc(var(--spacing) * 700);
  --mds-stepper-bar-scrollbar-size: 6px;
  --mds-stepper-bar-scrollbar-radius: var(--magma-radius-full);
  --mds-stepper-bar-scrollbar-thumb-background: rgb(var(--magma-accent-emphasis));
  --mds-stepper-bar-scrollbar-track-background: rgb(var(--magma-wash-base));
}

Targeting Shadow Parts for Deep Customization

The two documented shadow parts - items (the indicator track wrapper) and contents (the content panel wrapper) - let you apply layout overrides that CSS custom properties cannot express. Limit ::part() use to structural needs only; prefer the --mds-stepper-bar-* properties for everything else.

mds-stepper-bar::part(items) {
  padding-block: calc(var(--spacing) * 400);
  border-bottom: 1px solid rgb(var(--magma-border-muted));
}

mds-stepper-bar::part(contents) {
  padding-block: calc(var(--spacing) * 600);
}