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

Basic Tab Group with Managed Panels

The canonical form. Put <mds-tab-item> elements in the default slot and one content element per tab in the named content slot. Mark the initially-visible tab with selected. Panels are wired up by document order - the first [slot=content] element is paired with the first <mds-tab-item>.

<mds-tab>
  <mds-tab-item label="Panoramica" selected></mds-tab-item>
  <mds-tab-item label="Dettagli"></mds-tab-item>
  <mds-tab-item label="Allegati"></mds-tab-item>

  <div slot="content">
    <mds-text>Contenuto della scheda Panoramica.</mds-text>
  </div>
  <div slot="content">
    <mds-text>Contenuto della scheda Dettagli.</mds-text>
  </div>
  <div slot="content">
    <mds-text>Contenuto della scheda Allegati.</mds-text>
  </div>
</mds-tab>

Listening to Tab Changes

Listen to the mdsTabChange event to react when the active panel changes. The event detail carries the zero-based id (index) and the optional value of the newly selected <mds-tab-item>.

<mds-tab id="schede-pratica">
  <mds-tab-item label="Anagrafica" value="anagrafica" selected></mds-tab-item>
  <mds-tab-item label="Documenti" value="documenti"></mds-tab-item>
  <mds-tab-item label="Pagamenti" value="pagamenti"></mds-tab-item>
</mds-tab>

<script>
  document.querySelector('#schede-pratica').addEventListener('mdsTabChange', (e) => {
    console.log('scheda attiva:', e.detail.id, e.detail.value);
  });
</script>

Tab Items with Icons

Pass an icon slug to <mds-tab-item> via the icon prop. Icon position defaults to left; use icon-position="right" for forward-navigation tabs.

<mds-tab>
  <mds-tab-item label="Utente" icon="mi/baseline/person" selected></mds-tab-item>
  <mds-tab-item label="Impostazioni" icon="mi/baseline/settings"></mds-tab-item>
  <mds-tab-item label="Notifiche" icon="mi/baseline/notifications"></mds-tab-item>

  <div slot="content"><mds-text>Profilo utente.</mds-text></div>
  <div slot="content"><mds-text>Impostazioni account.</mds-text></div>
  <div slot="content"><mds-text>Cronologia notifiche.</mds-text></div>
</mds-tab>

Fill the Available Width

Set fill when the tab strip should stretch to occupy the full container width instead of hugging its content.

<mds-tab fill>
  <mds-tab-item label="Riepilogo" selected></mds-tab-item>
  <mds-tab-item label="Cronologia"></mds-tab-item>
  <mds-tab-item label="Statistiche"></mds-tab-item>

  <div slot="content"><mds-text>Riepilogo pratica.</mds-text></div>
  <div slot="content"><mds-text>Registro modifiche.</mds-text></div>
  <div slot="content"><mds-text>Dati statistici.</mds-text></div>
</mds-tab>

Vertical Direction

Use direction="vertical" to stack the tab strip on the side. Pair it with --mds-tab-direction-vertical-columns to control the column widths of the sidebar and the content area.

<mds-tab direction="vertical">
  <mds-tab-item label="Dati generali" selected></mds-tab-item>
  <mds-tab-item label="Indirizzi"></mds-tab-item>
  <mds-tab-item label="Contatti"></mds-tab-item>

  <div slot="content"><mds-text>Dati generali.</mds-text></div>
  <div slot="content"><mds-text>Indirizzi registrati.</mds-text></div>
  <div slot="content"><mds-text>Recapiti di contatto.</mds-text></div>
</mds-tab>

Fade Animation

Switch to animation="fade" to highlight the selected tab in place instead of moving the slider indicator. The panels switch without animation in both modes.

<mds-tab animation="fade">
  <mds-tab-item label="Prima" selected></mds-tab-item>
  <mds-tab-item label="Seconda"></mds-tab-item>

  <div slot="content"><mds-text>Pannello 1.</mds-text></div>
  <div slot="content"><mds-text>Pannello 2.</mds-text></div>
</mds-tab>

Overflow Shadow for Many Tabs

Enable overflow when the tab strip can contain more items than the viewport permits. Left and right inset shadows appear whenever tabs overflow their container, signalling that scrolling is possible.

<mds-tab overflow>
  <mds-tab-item label="Gennaio" selected></mds-tab-item>
  <mds-tab-item label="Febbraio"></mds-tab-item>
  <mds-tab-item label="Marzo"></mds-tab-item>
  <mds-tab-item label="Aprile"></mds-tab-item>
  <mds-tab-item label="Maggio"></mds-tab-item>
  <mds-tab-item label="Giugno"></mds-tab-item>
  <mds-tab-item label="Luglio"></mds-tab-item>
  <mds-tab-item label="Agosto"></mds-tab-item>
  <mds-tab-item label="Settembre"></mds-tab-item>
  <mds-tab-item label="Ottobre"></mds-tab-item>
  <mds-tab-item label="Novembre"></mds-tab-item>
  <mds-tab-item label="Dicembre"></mds-tab-item>
</mds-tab>

Scrollbar for Accessible Overflow

Use scrollbar instead of (or alongside) overflow to expose the native horizontal scrollbar. This is the accessible complement for users who navigate via keyboard or who have motor difficulties.

<mds-tab scrollbar overflow>
  <mds-tab-item label="Sezione A" selected></mds-tab-item>
  <mds-tab-item label="Sezione B"></mds-tab-item>
  <mds-tab-item label="Sezione C"></mds-tab-item>
  <mds-tab-item label="Sezione D"></mds-tab-item>
  <mds-tab-item label="Sezione E"></mds-tab-item>
</mds-tab>

Sizing

Set size on the parent to scale all tabs uniformly. Do not set size on individual <mds-tab-item> elements - the parent propagates the value automatically.

<!-- Compact strip, e.g. inside a sidebar or dense toolbar -->
<mds-tab size="sm">
  <mds-tab-item label="Vista elenco" selected></mds-tab-item>
  <mds-tab-item label="Vista griglia"></mds-tab-item>
</mds-tab>

Navigation Links (href on Tab Items)

When each tab leads to an anchor, another page or a route, set href on every <mds-tab-item> and omit the content slot: the items render as links, the browser follows them (in a new tab on a modifier or middle click) and the strip keeps the selected item highlighted. The page content is driven by navigation, not by the managed-panels mechanism.

<mds-tab>
  <mds-tab-item href="#sezione-1" label="Introduzione" selected></mds-tab-item>
  <mds-tab-item href="#sezione-2" label="Requisiti"></mds-tab-item>
  <mds-tab-item href="#sezione-3" label="Conclusioni"></mds-tab-item>
</mds-tab>

Client-Side Routing (href on Tab Items)

In a single-page app keep href on the items and register the router once with NavigationService, from @maggioli-design-system/magma/services: a plain click on an item is routed on the client and the selection still moves, with no listener per item. A modifier or middle click stays with the browser, which opens the link in a new tab while the strip stays as it is.

<mds-tab id="sezioni">
  <mds-tab-item href="/pratiche" label="Pratiche" selected></mds-tab-item>
  <mds-tab-item href="/documenti" label="Documenti"></mds-tab-item>
  <mds-tab-item href="/pagamenti" label="Pagamenti"></mds-tab-item>
</mds-tab>

<script type="module">
  import { NavigationService } from '@maggioli-design-system/magma/services';

  NavigationService.setHandler((href) => router.navigate(href));
</script>

Without a registered router, cancel the click on the items and route by hand: the component honours preventDefault() and still moves the selection. Leave a modifier click alone.

<script>
  document.querySelectorAll('#sezioni mds-tab-item').forEach((item) => {
    item.addEventListener('click', (event) => {
      if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;
      event.preventDefault();
      router.navigate(item.href);
    });
  });
</script>

Disabled Tab Item

Mark an individual tab as unavailable with disabled. The parent’s selection mechanism skips it; the tab is removed from the tab order automatically.

<mds-tab>
  <mds-tab-item label="Attivo" selected></mds-tab-item>
  <mds-tab-item label="Non disponibile" disabled></mds-tab-item>
  <mds-tab-item label="Altro"></mds-tab-item>

  <div slot="content"><mds-text>Contenuto disponibile.</mds-text></div>
  <div slot="content"><mds-text>Contenuto non disponibile.</mds-text></div>
  <div slot="content"><mds-text>Altro contenuto.</mds-text></div>
</mds-tab>

Styling Customization

Style the component only through its documented --mds-tab-* CSS custom properties. Set them on the host or a parent selector; use semantic color roles via rgb(var(--magma-<role>)) so dark mode and high-contrast modes keep working.

.scheda-primaria mds-tab {
  --mds-tab-tabs-background: rgb(var(--magma-accent-surface));
  --mds-tab-tabs-radius: var(--magma-radius-xl);
  --mds-tab-item-selected-background: rgb(var(--magma-accent-emphasis));
  --mds-tab-item-selected-color: rgb(var(--magma-accent-on-emphasis));
  --mds-tab-transition-duration: 0.3s;
}