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

Basic Navigation Trail

The canonical form. Slot one <mds-breadcrumb-item> per level and mark the current depth with selected. The back arrow is shown by default.

<mds-breadcrumb>
  <mds-breadcrumb-item label="Home"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Archivio pratiche"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Pratica 2024/001" selected></mds-breadcrumb-item>
</mds-breadcrumb>

Without the Back Arrow

Add the hide-back attribute for display-only or shallow breadcrumbs where reverse navigation adds no value. The back arrow is shown by default, so this is an explicit opt-out.

<mds-breadcrumb hide-back>
  <mds-breadcrumb-item label="Impostazioni"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Profilo utente" selected></mds-breadcrumb-item>
</mds-breadcrumb>

Listening for Navigation Changes

mdsBreadcrumbChange fires whenever a child item is clicked or the back arrow is activated. The detail carries the zero-based id string of the newly selected item and a caller element: the clicked item, or for the back arrow the item that was current before the step.

<mds-breadcrumb id="nav">
  <mds-breadcrumb-item label="Dashboard"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Documenti"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Fatture" selected></mds-breadcrumb-item>
</mds-breadcrumb>

<script>
  document.getElementById('nav').addEventListener('mdsBreadcrumbChange', (e) => {
    console.log('Livello selezionato:', e.detail.id);
    console.log('Elemento:', e.detail.caller);
  });
</script>

Programmatic Selection

Set selected in the markup on the item you want active on load: the parent reads it to set the back button state (disabled on the first item). Setting selected later from JavaScript emits no event, so the parent neither clears the other items nor updates the back button.

<mds-breadcrumb>
  <mds-breadcrumb-item label="Progetto Alpha" selected></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Sprint 3"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Attivita"></mds-breadcrumb-item>
</mds-breadcrumb>

Item Label via label Prop

Always set the text with the label prop on <mds-breadcrumb-item>: the item has no slot. The prop is reflected as an HTML attribute, enabling CSS attribute selectors and framework bindings.

<mds-breadcrumb>
  <mds-breadcrumb-item label="Area riservata"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Gestione utenti"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Nuovo utente" selected></mds-breadcrumb-item>
</mds-breadcrumb>

Styling Customization via CSS Custom Properties

Apply --mds-breadcrumb-* vars on the host to retheme the whole trail at once. Use semantic color roles wrapped in rgb(var(--magma-<role>)) so dark mode and high-contrast modes keep working. Changes on the parent propagate into the child items because the item vars inherit from the parent vars. The current item’s color is set on the items: the parent’s --mds-breadcrumb-button-color-current is not read by them.

.sidebar-nav mds-breadcrumb {
  --mds-breadcrumb-button-color: rgb(var(--magma-accent-fg));
  --mds-breadcrumb-button-color-hover: rgb(var(--magma-text-default));
  --mds-breadcrumb-arrow-depth-color: rgb(var(--magma-accent-fg));
}

.sidebar-nav mds-breadcrumb-item {
  --mds-breadcrumb-item-button-color-selected: rgb(var(--magma-text-default));
}

Per-Item Styling via ::part(button)

When you need to restyle a single item’s inner button beyond what the CSS vars allow, target the documented ::part(button) on <mds-breadcrumb-item>. This is the only supported shadow-part surface on the child component.

mds-breadcrumb-item[selected]::part(button) {
  font-weight: bold;
  letter-spacing: 0.02em;
}