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

Basic Column Headers

Place <mds-table-header> as a direct child of <mds-table> and fill its default slot with one <mds-table-header-cell> per column. Use the label prop on each cell - it is the only text source the cell needs.

<mds-table>
  <mds-table-header>
    <mds-table-header-cell label="Nome"></mds-table-header-cell>
    <mds-table-header-cell label="Email"></mds-table-header-cell>
    <mds-table-header-cell label="Data registrazione"></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body>
    <!-- mds-table-row elements -->
  </mds-table-body>
</mds-table>

Sortable Columns

Add the sortable attribute on the <mds-table-header-cell> elements whose column should be sortable. The cell cycles through none, ascending, and descending on each click and re-orders the corresponding body rows automatically.

<mds-table>
  <mds-table-header>
    <mds-table-header-cell sortable label="Cognome"></mds-table-header-cell>
    <mds-table-header-cell sortable label="Data"></mds-table-header-cell>
    <mds-table-header-cell label="Note"></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body>
    <!-- mds-table-row elements -->
  </mds-table-body>
</mds-table>

Selectable Table with Master Checkbox

Enable row selection by adding selectable on <mds-table>. The table propagates the prop down to <mds-table-header>, which automatically renders the master “select all” checkbox as the first column. Never set selectable directly on <mds-table-header> - drive it from the table.

<mds-table selectable>
  <mds-table-header>
    <mds-table-header-cell label="Utente"></mds-table-header-cell>
    <mds-table-header-cell label="Ruolo"></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body>
    <mds-table-row value="1">
      <mds-table-cell>Mario Rossi</mds-table-cell>
      <mds-table-cell>Amministratore</mds-table-cell>
    </mds-table-row>
    <mds-table-row value="2">
      <mds-table-cell>Giulia Bianchi</mds-table-cell>
      <mds-table-cell>Editor</mds-table-cell>
    </mds-table-row>
  </mds-table-body>
</mds-table>

Reacting to Selection Changes

Listen for mdsTableSelectionChange on <mds-table> to receive the array of selected rows whenever the master checkbox or any individual row checkbox changes.

<mds-table selectable id="tabella-utenti">
  <mds-table-header>
    <mds-table-header-cell label="Utente"></mds-table-header-cell>
    <mds-table-header-cell label="Stato"></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body>
    <mds-table-row value="alice">
      <mds-table-cell>Alice Verdi</mds-table-cell>
      <mds-table-cell>Attivo</mds-table-cell>
    </mds-table-row>
    <mds-table-row value="bob">
      <mds-table-cell>Bob Neri</mds-table-cell>
      <mds-table-cell>Sospeso</mds-table-cell>
    </mds-table-row>
  </mds-table-body>
</mds-table>

<script>
  document.getElementById('tabella-utenti').addEventListener('mdsTableSelectionChange', (e) => {
    console.log('Righe selezionate:', e.detail.rows);
  });
</script>

Actions Column - Automatic Header Cell

When any <mds-table-row> exposes a [slot="action"], <mds-table-header> automatically appends a right-aligned, localized header cell (“Action”, “Azione” in Italian). No extra markup is required in the header - just place your action buttons in the row slots.

<mds-table>
  <mds-table-header>
    <mds-table-header-cell label="Documento"></mds-table-header-cell>
    <mds-table-header-cell label="Dimensione"></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body>
    <mds-table-row>
      <mds-table-cell>Relazione annuale.pdf</mds-table-cell>
      <mds-table-cell>2,4 MB</mds-table-cell>
      <mds-button
        slot="action"
        icon="mi/baseline/download"
        title="Scarica"
        variant="primary"
        tone="text"
      ></mds-button>
    </mds-table-row>
  </mds-table-body>
</mds-table>

Batch Actions with Selection

When selectable is set and the table has a batch-action slot, a batch-actions toolbar slides in whenever rows are selected. The toolbar is owned by <mds-table>: every selection change, from a row checkbox or from the master checkbox in <mds-table-header>, updates its count and visibility.

<mds-table selectable>
  <mds-table-header>
    <mds-table-header-cell label="Nome file"></mds-table-header-cell>
    <mds-table-header-cell label="Tipo"></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body>
    <mds-table-row value="doc1">
      <mds-table-cell>contratto.pdf</mds-table-cell>
      <mds-table-cell>PDF</mds-table-cell>
    </mds-table-row>
    <mds-table-row value="doc2">
      <mds-table-cell>allegato.docx</mds-table-cell>
      <mds-table-cell>Word</mds-table-cell>
    </mds-table-row>
  </mds-table-body>
  <mds-button slot="batch-action" label="Elimina selezionati" variant="error" tone="text"></mds-button>
  <mds-button slot="batch-action" label="Esporta" variant="primary" tone="outline"></mds-button>
</mds-table>

Styling the Actions Part

The auto-generated actions header cell is exposed as the actions shadow part. Target it with ::part(actions) to adjust alignment or other visual properties.

mds-table-header::part(actions) {
  text-align: center;
  min-width: 8rem;
}