Correct and idiomatic ways to use the <mds-tab-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 Group

The canonical form. Place <mds-tab-item> elements in the default slot of <mds-tab>, with one matching panel element per item in the content slot. Mark the initially active tab with selected.

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

  <div slot="content">
    <p>Contenuto della scheda Dettagli.</p>
  </div>
  <div slot="content">
    <p>Elenco degli allegati.</p>
  </div>
  <div slot="content">
    <p>Cronologia delle modifiche.</p>
  </div>
</mds-tab>

Tabs with Icons

Use the icon prop to add a glyph. icon-position defaults to left; set it to right for affordance glyphs such as external-link hints.

<mds-tab>
  <mds-tab-item label="Profilo" icon="mi/baseline/person" selected></mds-tab-item>
  <mds-tab-item label="Impostazioni" icon="mi/baseline/settings"></mds-tab-item>
  <mds-tab-item label="Apri in nuova finestra" icon="mi/baseline/open-in-new" icon-position="right"></mds-tab-item>

  <div slot="content"><p>Sezione profilo.</p></div>
  <div slot="content"><p>Sezione impostazioni.</p></div>
  <div slot="content"><p>Sezione apertura esterna.</p></div>
</mds-tab>

Disabled Tab

Set the disabled boolean attribute to block selection via pointer and keyboard.

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

  <div slot="content"><p>Contenuto attivo.</p></div>
  <div slot="content"><p>Contenuto non ancora disponibile.</p></div>
</mds-tab>

Controlled Selection via value and Event

Use value to identify which tab was activated in the mdsTabItemSelect (or the parent’s mdsTabChange) payload, instead of relying on DOM index.

<mds-tab id="schede-pratica">
  <mds-tab-item label="Dati generali" value="dati" selected></mds-tab-item>
  <mds-tab-item label="Documenti" value="documenti"></mds-tab-item>
  <mds-tab-item label="Note" value="note"></mds-tab-item>

  <div slot="content"><p>Dati generali.</p></div>
  <div slot="content"><p>Documenti allegati.</p></div>
  <div slot="content"><p>Note operative.</p></div>
</mds-tab>

<script>
  document.getElementById('schede-pratica').addEventListener('mdsTabChange', (e) => {
    console.log('Tab attiva:', e.detail.value); // 'dati' | 'documenti' | 'note'
  });
</script>

Consistent Sizing via the Parent

Set size on <mds-tab> once; the parent propagates it to every child item automatically. Do not set size on individual items when they all share the same parent.

<!-- Tutti i tab usano size="sm" -->
<mds-tab size="sm">
  <mds-tab-item label="Riepilogo" selected></mds-tab-item>
  <mds-tab-item label="Dettaglio"></mds-tab-item>

  <div slot="content"><p>Riepilogo.</p></div>
  <div slot="content"><p>Dettaglio.</p></div>
</mds-tab>

Link Items via href

Set href on every item to make the strip a navigation: each item is a link the browser follows instead of a tab switching a panel, so omit the content slot. <mds-tab-item> has no target prop, so a plain click opens the link in the same window; a modifier or middle click opens it in a new tab. In a single-page app, register the router once with NavigationService (from @maggioli-design-system/magma/services): a plain click on an item is then routed on the client, and the selection still moves.

<mds-tab>
  <mds-tab-item label="Pratiche" href="/pratiche" selected></mds-tab-item>
  <mds-tab-item label="Documenti" href="/documenti"></mds-tab-item>
  <mds-tab-item label="Pagamenti" href="/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 item and route by hand: the component honours preventDefault(). Leave a modifier click alone, so that the browser opens the link in a new tab.

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

Async Loading Tab via await

Set await while the tab’s content is loading. The item renders an inline spinner and blocks interaction until you remove the attribute.

<mds-tab>
  <mds-tab-item label="Anteprima" await selected></mds-tab-item>
  <mds-tab-item label="Sorgente"></mds-tab-item>

  <div slot="content"><p>Caricamento in corso...</p></div>
  <div slot="content"><p>Sorgente del documento.</p></div>
</mds-tab>

Vertical Layout

Set direction="vertical" on the parent to stack the tabs alongside the panels.

<mds-tab direction="vertical">
  <mds-tab-item label="Generale" selected></mds-tab-item>
  <mds-tab-item label="Sicurezza"></mds-tab-item>
  <mds-tab-item label="Notifiche"></mds-tab-item>

  <div slot="content"><p>Impostazioni generali.</p></div>
  <div slot="content"><p>Impostazioni di sicurezza.</p></div>
  <div slot="content"><p>Preferenze notifiche.</p></div>
</mds-tab>

CSS Customization

Style items only through the documented --mds-tab-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.

.schede-contratto mds-tab-item {
  --mds-tab-item-default-background: rgb(var(--magma-wash-soft));
  --mds-tab-item-hover-background: rgb(var(--magma-wash-base));
  --mds-tab-item-selected-background: rgb(var(--magma-accent-surface));
}