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

Basic Navigation Bar

The canonical form. Place one <mds-tab-bar-item> per destination. Provide icon as a slug from the Magma icon library and the text via the label prop. Mark the initially active item with selected.

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

Reacting to Tab Changes

Listen for mdsTabBarChange on the host. The event detail carries index - the zero-based position of the newly selected item - which you use to switch the visible view or panel.

<mds-tab-bar id="app-nav">
  <mds-tab-bar-item icon="mi/baseline/home" label="Home" selected></mds-tab-bar-item>
  <mds-tab-bar-item icon="mi/baseline/inbox" label="Messaggi"></mds-tab-bar-item>
  <mds-tab-bar-item icon="mi/baseline/settings" label="Impostazioni"></mds-tab-bar-item>
</mds-tab-bar>

<script>
  document.querySelector('#app-nav').addEventListener('mdsTabBarChange', (e) => {
    const activeIndex = e.detail.index;
    showView(activeIndex);
  });
</script>

Setting the Initial Active Tab Programmatically

Set selected on exactly one child to control the starting state. If you later need to change the active item from outside - for example, after a router navigation - set selected on the new item and remove it from the previous one yourself: the parent syncs the siblings only when an item is clicked, and emits no mdsTabBarChange for a change made from code.

<!-- Second item active on load -->
<mds-tab-bar>
  <mds-tab-bar-item icon="mi/baseline/home" label="Home"></mds-tab-bar-item>
  <mds-tab-bar-item icon="mi/baseline/explore" label="Scopri" selected></mds-tab-bar-item>
  <mds-tab-bar-item icon="mi/baseline/favorite" label="Preferiti"></mds-tab-bar-item>
</mds-tab-bar>

Adjusting Label Typography

Use typography on individual items to match the text density to the surrounding chrome. The prop accepts "tip" (default, smaller) or "option" (slightly larger). You can mix values if items carry different visual weight.

<mds-tab-bar>
  <mds-tab-bar-item icon="mi/baseline/home" label="Home" typography="option" selected></mds-tab-bar-item>
  <mds-tab-bar-item icon="mi/baseline/inbox" label="Posta" 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 via CSS Custom Properties

Style individual items through the documented --mds-tab-bar-item-* CSS custom properties. Set them on the specific item or on a parent selector. Use semantic color roles via rgb(var(--magma-<role>)) so dark mode and high-contrast keep working.

/* Brand-specific active color for the whole bar */
mds-tab-bar mds-tab-bar-item {
  --mds-tab-bar-item-color-selected: rgb(var(--magma-accent-fg));
}

/* A single item with a distinct idle color */
mds-tab-bar-item.priority {
  --mds-tab-bar-item-color: rgb(var(--magma-warning-text-default));
}