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

Basic Tab Bar

The canonical form. Place all items directly inside <mds-tab-bar>. Give each item an icon and set its text with the label prop. The parent assigns ids automatically and coordinates selection.

<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-item icon="mi/baseline/notifications" label="Notifiche"></mds-tab-bar-item>
  <mds-tab-bar-item icon="mi/baseline/person" label="Profilo"></mds-tab-bar-item>
</mds-tab-bar>

Setting the Initial Active Tab

Mark one item as pre-selected on first render with the selected boolean attribute. Do not set more than one item as selected - the parent enforces mutual exclusivity once the first click event fires.

<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-item icon="mi/baseline/notifications" label="Notifiche"></mds-tab-bar-item>
</mds-tab-bar>

Listening for Selection Changes

Listen to mdsTabBarItemSelect on the item to react when a specific tab becomes active, or listen to mdsTabBarChange on the parent to receive the zero-based index of the newly selected item.

<mds-tab-bar id="main-nav">
  <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-item icon="mi/baseline/person" label="Profilo"></mds-tab-bar-item>
</mds-tab-bar>

<script>
  document.querySelector('#main-nav').addEventListener('mdsTabBarChange', (e) => {
    console.log('tab selezionato:', e.detail.index);
  });
</script>

Driving Selection Programmatically

Set the selected prop on the desired item from JavaScript, and remove it from the previously selected one: the item updates its own visual state, but the parent syncs the siblings only on the next click and emits no mdsTabBarChange for a change made from code. Do not address the items by your own id: the bar replaces it with mds-tab-bar-item-<index> when it loads.

<mds-tab-bar id="wizard-nav">
  <mds-tab-bar-item icon="mi/baseline/person" label="Profilo"></mds-tab-bar-item>
  <mds-tab-bar-item icon="mi/baseline/lock" label="Sicurezza"></mds-tab-bar-item>
  <mds-tab-bar-item
    icon="mi/baseline/notifications"
    label="Notifiche"
  ></mds-tab-bar-item>
</mds-tab-bar>

<script>
  document.querySelectorAll('#wizard-nav mds-tab-bar-item')[1].selected = true;
</script>

Larger Label Typography

Use typography="option" for a slightly more prominent label when the tab bar sits in a layout where tip (the default) reads too small.

<mds-tab-bar>
  <mds-tab-bar-item
    icon="mi/baseline/dashboard"
    label="Dashboard"
    typography="option"
    selected
  ></mds-tab-bar-item>
  <mds-tab-bar-item
    icon="mi/baseline/bar-chart"
    label="Statistiche"
    typography="option"
  ></mds-tab-bar-item>
  <mds-tab-bar-item
    icon="mi/baseline/settings"
    label="Impostazioni"
    typography="option"
  ></mds-tab-bar-item>
</mds-tab-bar>

Styling Customization

Override colors through the four documented --mds-tab-bar-item-* CSS custom properties. Set them on the host or a parent selector; use semantic color roles via rgb(var(--magma-<role>)) so dark mode keeps working.

.app-bottom-nav mds-tab-bar-item {
  --mds-tab-bar-item-background: rgb(var(--magma-wash-base));
  --mds-tab-bar-item-color: rgb(var(--magma-text-muted));
  --mds-tab-bar-item-background-selected: rgb(var(--magma-accent-surface-subtle));
  --mds-tab-bar-item-color-selected: rgb(var(--magma-accent-fg));
}