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

Minimal Step Inside a Stepper Bar

Place <mds-stepper-bar-item> elements as direct children of <mds-stepper-bar>. Each item requires label and icon. items-done on the parent drives the done and current state of each child automatically.

<mds-stepper-bar items-done="1">
  <mds-stepper-bar-item
    icon="mi/baseline/person"
    label="Dati personali"
  ></mds-stepper-bar-item>
  <mds-stepper-bar-item
    icon="mi/baseline/location-on"
    label="Indirizzo"
  ></mds-stepper-bar-item>
  <mds-stepper-bar-item
    icon="mi/baseline/payment"
    label="Pagamento"
  ></mds-stepper-bar-item>
</mds-stepper-bar>

Distinct Icon for the Completed State

Set icon-checked to a different slug when the done state should show a different glyph - for example a checkmark. When omitted, icon-checked defaults to icon.

<mds-stepper-bar items-done="2">
  <mds-stepper-bar-item
    icon="mi/baseline/person"
    icon-checked="mi/baseline/done"
    label="Dati personali"
  ></mds-stepper-bar-item>
  <mds-stepper-bar-item
    icon="mi/baseline/location-on"
    icon-checked="mi/baseline/done"
    label="Indirizzo"
  ></mds-stepper-bar-item>
  <mds-stepper-bar-item
    icon="mi/baseline/payment"
    icon-checked="mi/baseline/done"
    label="Pagamento"
  ></mds-stepper-bar-item>
</mds-stepper-bar>

Showing the Ordinal Caption with step

Set the boolean step attribute to surface an auto-numbered “Step N” caption above the label. Use this for explicitly ordered flows where the ordinal number aids orientation.

<mds-stepper-bar items-done="1">
  <mds-stepper-bar-item
    step
    icon="mi/baseline/person"
    icon-checked="mi/baseline/done"
    label="Dati personali"
  ></mds-stepper-bar-item>
  <mds-stepper-bar-item
    step
    icon="mi/baseline/location-on"
    icon-checked="mi/baseline/done"
    label="Indirizzo"
  ></mds-stepper-bar-item>
  <mds-stepper-bar-item
    step
    icon="mi/baseline/payment"
    icon-checked="mi/baseline/done"
    label="Pagamento"
  ></mds-stepper-bar-item>
</mds-stepper-bar>

Status Badge via badge

Set badge to show the localized status pill (Completato / In corso / In coda). Prefer this when status legibility matters more than horizontal compactness.

<mds-stepper-bar items-done="2">
  <mds-stepper-bar-item
    badge
    icon="mi/baseline/person"
    icon-checked="mi/baseline/done"
    label="Dati personali"
  ></mds-stepper-bar-item>
  <mds-stepper-bar-item
    badge
    icon="mi/baseline/location-on"
    icon-checked="mi/baseline/done"
    label="Indirizzo"
  ></mds-stepper-bar-item>
  <mds-stepper-bar-item
    badge
    icon="mi/baseline/payment"
    label="Pagamento"
  ></mds-stepper-bar-item>
</mds-stepper-bar>

Carrying a Value for Event Handling

Set value on each item: the parent collects the values of the completed items, comma-joined, into the value of its mdsStepperBarChange detail. Listen to that event on the parent or a common ancestor.

<mds-stepper-bar id="stepper" items-done="1">
  <mds-stepper-bar-item
    value="dati-personali"
    icon="mi/baseline/person"
    icon-checked="mi/baseline/done"
    label="Dati personali"
  ></mds-stepper-bar-item>
  <mds-stepper-bar-item
    value="indirizzo"
    icon="mi/baseline/location-on"
    icon-checked="mi/baseline/done"
    label="Indirizzo"
  ></mds-stepper-bar-item>
  <mds-stepper-bar-item
    value="pagamento"
    icon="mi/baseline/payment"
    icon-checked="mi/baseline/done"
    label="Pagamento"
  ></mds-stepper-bar-item>
</mds-stepper-bar>

<script>
  document.getElementById('stepper').addEventListener('mdsStepperBarChange', (e) => {
    console.log('step completati:', e.detail.value, 'step corrente:', e.detail.step);
  });
</script>

Pairing Step Content via the content Slot

Place panel elements with slot="content" inside <mds-stepper-bar> - one per item in order. The parent shows only the panel matching the current step (it puts the hidden class on the others, so the page needs a .hidden { display: none } rule, such as the Tailwind utility).

<mds-stepper-bar items-done="1">
  <mds-stepper-bar-item icon="mi/baseline/person" icon-checked="mi/baseline/done" label="Dati personali"></mds-stepper-bar-item>
  <mds-stepper-bar-item icon="mi/baseline/location-on" icon-checked="mi/baseline/done" label="Indirizzo"></mds-stepper-bar-item>
  <mds-stepper-bar-item icon="mi/baseline/payment" label="Pagamento"></mds-stepper-bar-item>

  <div slot="content">
    <p>Inserisci il tuo nome e cognome.</p>
  </div>
  <div slot="content">
    <p>Inserisci il tuo indirizzo di spedizione.</p>
  </div>
  <div slot="content">
    <p>Scegli il metodo di pagamento.</p>
  </div>
</mds-stepper-bar>

Reducing Label Typography for Dense Bars

Lower the typography prop (default h6) when horizontal space is tight or when the label must blend with smaller surrounding text.

<mds-stepper-bar items-done="1">
  <mds-stepper-bar-item
    typography="label"
    icon="mi/baseline/person"
    icon-checked="mi/baseline/done"
    label="Dati personali"
  ></mds-stepper-bar-item>
  <mds-stepper-bar-item
    typography="label"
    icon="mi/baseline/location-on"
    icon-checked="mi/baseline/done"
    label="Indirizzo"
  ></mds-stepper-bar-item>
  <mds-stepper-bar-item
    typography="label"
    icon="mi/baseline/payment"
    label="Pagamento"
  ></mds-stepper-bar-item>
</mds-stepper-bar>

Styling Customization

Style items only through the documented --mds-stepper-bar-item-* CSS custom properties. Use semantic color roles via rgb(var(--magma-<role>)) so dark mode and high-contrast modes keep working. Target the ::part(badge) surface only when a deep visual override of the badge wrapper is required.

.checkout-flow mds-stepper-bar-item {
  --mds-stepper-bar-item-icon-background-current: rgb(var(--magma-accent-emphasis));
  --mds-stepper-bar-item-icon-color-current: rgb(var(--magma-accent-on-emphasis));
  --mds-stepper-bar-item-icon-background-done: rgb(var(--magma-success-emphasis));
  --mds-stepper-bar-item-progress-color: rgb(var(--magma-success-emphasis));
  --mds-stepper-bar-item-min-width: 160px;
}