Common incorrect uses of <mds-tab-bar-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-tab-bar>

<mds-tab-bar-item> relies on the parent to assign its id, listen for mdsTabBarItemSelect, and drive mutual exclusivity. Without the parent, the item has no stable id, selection does not propagate, and no other item is deselected when this one is clicked.

<!-- INCORRECT -->
<mds-tab-bar-item icon="mi/baseline/home" label="Home" selected></mds-tab-bar-item>

<!-- CORRECT -->
<mds-tab-bar>
  <mds-tab-bar-item icon="mi/baseline/home" label="Home" selected></mds-tab-bar-item>
  <mds-tab-bar-item icon="mi/baseline/search" label="Cerca"></mds-tab-bar-item>
</mds-tab-bar>

Do Not Use the Deprecated Default Slot for Text

Setting the text via the default slot is deprecated. Slotted text is read into label, and any nested HTML is stripped with a console warning. Use the label prop instead.

<!-- INCORRECT -->
<mds-tab-bar>
  <mds-tab-bar-item icon="mi/baseline/home">Home</mds-tab-bar-item>
  <mds-tab-bar-item icon="mi/baseline/search"><strong>Cerca</strong></mds-tab-bar-item>
</mds-tab-bar>

<!-- CORRECT -->
<mds-tab-bar>
  <mds-tab-bar-item icon="mi/baseline/home" label="Home"></mds-tab-bar-item>
  <mds-tab-bar-item icon="mi/baseline/search" label="Cerca"></mds-tab-bar-item>
</mds-tab-bar>

Do Not Slot <mds-icon> to Add an Icon

The icon prop renders the glyph through the shared icon service and positions it above the label automatically. Slotting <mds-icon> puts it in the deprecated default slot, where it is stripped and misaligns.

<!-- INCORRECT -->
<mds-tab-bar>
  <mds-tab-bar-item>
    <mds-icon name="mi/baseline/home"></mds-icon>
    Home
  </mds-tab-bar-item>
</mds-tab-bar>

<!-- CORRECT -->
<mds-tab-bar>
  <mds-tab-bar-item icon="mi/baseline/home" label="Home"></mds-tab-bar-item>
</mds-tab-bar>

Do Not Set selected="false" to Deselect

selected is a boolean attribute. The item happens to style selected="false" as unselected, but the attribute stays on the element and contradicts the state for attribute selectors and checks. Remove the attribute or set the property to undefined to deselect.

<!-- INCORRECT -->
<mds-tab-bar>
  <mds-tab-bar-item icon="mi/baseline/home" label="Home" selected="false"></mds-tab-bar-item>
</mds-tab-bar>

<!-- CORRECT -->
<mds-tab-bar>
  <mds-tab-bar-item icon="mi/baseline/home" label="Home"></mds-tab-bar-item>
</mds-tab-bar>

Do Not Listen to Raw Click Events for Tab Changes

<mds-tab-bar-item> emits mdsTabBarItemSelect when selected; <mds-tab-bar> re-emits mdsTabBarChange with the resolved index. Listening to the native click event gives you no index, and it also fires on clicks that select nothing (every other click on the item that is already active).

<!-- INCORRECT -->
<mds-tab-bar id="nav">
  <mds-tab-bar-item icon="mi/baseline/home" label="Home"></mds-tab-bar-item>
</mds-tab-bar>
<script>
  document.querySelector('mds-tab-bar-item').addEventListener('click', handler);
</script>

<!-- CORRECT -->
<mds-tab-bar id="nav">
  <mds-tab-bar-item icon="mi/baseline/home" label="Home"></mds-tab-bar-item>
</mds-tab-bar>
<script>
  document.querySelector('#nav').addEventListener('mdsTabBarChange', handler);
</script>

Do Not Use an Invalid typography Value

typography accepts only "tip" (default) or "option". Passing any other value - such as "caption" or "label" - is outside the typed TypographySmallerType: it is passed unchecked to the inner <mds-text>, so the label silently leaves the tab bar’s type scale.

<!-- INCORRECT -->
<mds-tab-bar>
  <mds-tab-bar-item icon="mi/baseline/home" label="Home" typography="caption"></mds-tab-bar-item>
</mds-tab-bar>

<!-- CORRECT -->
<mds-tab-bar>
  <mds-tab-bar-item icon="mi/baseline/home" label="Home" typography="option"></mds-tab-bar-item>
</mds-tab-bar>