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

Basic Breadcrumb Trail

The canonical form. Place <mds-breadcrumb-item> elements as direct children of <mds-breadcrumb>. Use the label prop for each step’s text.

<mds-breadcrumb>
  <mds-breadcrumb-item label="Home"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Archivio"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Dettaglio documento"></mds-breadcrumb-item>
</mds-breadcrumb>

Seeding the Active Depth with selected

Set selected on the item that represents the user’s current location on first render. The parent <mds-breadcrumb> takes over selection management after that; do not set selected on more than one item at a time.

<mds-breadcrumb>
  <mds-breadcrumb-item label="Home"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Archivio"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Documenti" selected></mds-breadcrumb-item>
</mds-breadcrumb>

Listening for Navigation Changes

Listen to mdsBreadcrumbItemSelect on the item, or to mdsBreadcrumbChange, which the parent <mds-breadcrumb> emits after updating the selection, to react when the user navigates to a different depth.

<mds-breadcrumb id="nav">
  <mds-breadcrumb-item label="Home"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Pratiche"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Dettaglio" selected></mds-breadcrumb-item>
</mds-breadcrumb>

<script>
  document.querySelector('#nav').addEventListener('mdsBreadcrumbChange', (e) => {
    console.log('profondita selezionata:', e.detail.id);
  });
</script>

Styling the Arrow Separator

Override --mds-breadcrumb-item-arrow-depth-color on the host or a parent selector to recolour the separator icon without touching the button label color. Use semantic color roles wrapped in rgb(var(--magma-<role>)) so dark mode keeps working.

.header-nav mds-breadcrumb-item {
  --mds-breadcrumb-item-arrow-depth-color: rgb(var(--magma-accent-fg));
}

Styling Button States

Override the button color and background tokens to match a custom surface. All three state variants - default, hover, and selected - have dedicated custom properties.

.sidebar-nav mds-breadcrumb-item {
  --mds-breadcrumb-item-button-color: rgb(var(--magma-text-muted));
  --mds-breadcrumb-item-button-color-hover: rgb(var(--magma-text-default));
  --mds-breadcrumb-item-button-color-selected: rgb(var(--magma-accent-fg));
  --mds-breadcrumb-item-button-background-selected: rgb(var(--magma-accent-surface-subtle));
}

Styling the Internal Button via ::part(button)

The internal <mds-button> is exposed as ::part(button). Use it only when the documented CSS custom properties are insufficient - for example to adjust padding or border radius for a product-specific surface.

.compact-nav mds-breadcrumb-item::part(button) {
  --mds-button-radius: var(--magma-radius-sm);
}