Common incorrect uses of <mds-breadcrumb-item>. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in agents/anti-patterns.md - they apply here too but are not repeated.

Do Not Use Outside <mds-breadcrumb>

<mds-breadcrumb-item> is a compound child; it communicates with its parent through internal events and relies on the parent to assign IDs, manage selection, and control the back button. Outside the parent it renders an isolated button with no selection management.

<!-- INCORRECT -->
<nav>
  <mds-breadcrumb-item label="Home"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Archivio"></mds-breadcrumb-item>
</nav>

<!-- CORRECT -->
<mds-breadcrumb>
  <mds-breadcrumb-item label="Home"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Archivio"></mds-breadcrumb-item>
</mds-breadcrumb>

Do Not Pass Text or HTML as Children

<mds-breadcrumb-item> has no default slot - it renders its text through an internal <mds-button> driven by the label prop. Anything placed between the tags (plain text or HTML) is ignored and never rendered. Always use the label prop.

<!-- INCORRECT -->
<mds-breadcrumb-item>Dettaglio</mds-breadcrumb-item>
<mds-breadcrumb-item><strong>Dettaglio</strong></mds-breadcrumb-item>

<!-- CORRECT -->
<mds-breadcrumb-item label="Dettaglio"></mds-breadcrumb-item>

Do Not Select More Than One Item at Initialisation

selected should be set on at most one item as the initial active depth. Marking multiple items selected puts the breadcrumb in an inconsistent state that the parent cannot resolve until the next click.

<!-- INCORRECT -->
<mds-breadcrumb>
  <mds-breadcrumb-item label="Home" selected></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Archivio" selected></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Dettaglio"></mds-breadcrumb-item>
</mds-breadcrumb>

<!-- CORRECT -->
<mds-breadcrumb>
  <mds-breadcrumb-item label="Home"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Archivio"></mds-breadcrumb-item>
  <mds-breadcrumb-item label="Dettaglio" selected></mds-breadcrumb-item>
</mds-breadcrumb>

Do Not Set selected="false" to Deselect

selected is a boolean attribute. Stencil reads the string "false" as false, but the attribute stays on the element: the item keeps the selected styling and ignores pointer clicks (:host([selected])), and the parent’s [selected] query still counts it. Remove the attribute entirely to deselect.

<!-- INCORRECT -->
<mds-breadcrumb-item label="Home" selected="false"></mds-breadcrumb-item>

<!-- CORRECT -->
<mds-breadcrumb-item label="Home"></mds-breadcrumb-item>

Do Not Listen for Native click to Track Navigation

The component emits mdsBreadcrumbItemSelect when a step is activated and the parent emits mdsBreadcrumbChange. A native click carries no depth, and it fires even on the already-selected (inert) item and on the separator arrow.

<!-- INCORRECT -->
<script>
  document.querySelector('mds-breadcrumb-item').addEventListener('click', (e) => {
    // no depth in the event; fires even on the selected/inert item
  });
</script>

<!-- CORRECT -->
<script>
  document.querySelector('mds-breadcrumb').addEventListener('mdsBreadcrumbChange', (e) => {
    console.log('nuovo passo attivo:', e.detail.id);
  });
</script>

Do Not Pierce Shadow DOM to Style Internals

The supported customization surface is the documented --mds-breadcrumb-item-* CSS custom properties and the ::part(button) export. Targeting internal classes directly couples your code to the shadow DOM implementation and will break on minor releases.

/* INCORRECT */
mds-breadcrumb-item >>> .icon {
  fill: red;
}

/* CORRECT */
mds-breadcrumb-item {
  --mds-breadcrumb-item-arrow-depth-color: rgb(var(--magma-accent-fg));
}