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

Plain Header Cell

The simplest form: a non-sortable column header that renders a styled label. Omit sortable for columns whose values should not be reordered.

<mds-table>
  <mds-table-header>
    <mds-table-header-cell label="Nome"></mds-table-header-cell>
    <mds-table-header-cell label="Ruolo"></mds-table-header-cell>
    <mds-table-header-cell label="Stato"></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body>
    <mds-table-row>
      <mds-table-cell>Mario Rossi</mds-table-cell>
      <mds-table-cell>Amministratore</mds-table-cell>
      <mds-table-cell>Attivo</mds-table-cell>
    </mds-table-row>
  </mds-table-body>
</mds-table>

Sortable Column Header

Add the sortable boolean attribute to enable the tri-state click cycle (none -> ascending -> descending -> none). The component manages sorting internally - no JavaScript wiring is required.

<mds-table>
  <mds-table-header>
    <mds-table-header-cell label="Cognome" sortable></mds-table-header-cell>
    <mds-table-header-cell label="Dipartimento" sortable></mds-table-header-cell>
    <mds-table-header-cell label="Note"></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body>
    <mds-table-row>
      <mds-table-cell>Bianchi</mds-table-cell>
      <mds-table-cell>Risorse Umane</mds-table-cell>
      <mds-table-cell>-</mds-table-cell>
    </mds-table-row>
    <mds-table-row>
      <mds-table-cell>Amendola</mds-table-cell>
      <mds-table-cell>Informatica</mds-table-cell>
      <mds-table-cell>-</mds-table-cell>
    </mds-table-row>
  </mds-table-body>
</mds-table>

Mixing Sortable and Non-Sortable Columns

Place sortable only on columns whose values are meaningfully orderable. Action columns or complex-content columns should remain non-sortable.

<mds-table>
  <mds-table-header>
    <mds-table-header-cell label="ID" sortable></mds-table-header-cell>
    <mds-table-header-cell label="Descrizione" sortable></mds-table-header-cell>
    <mds-table-header-cell label="Importo" sortable></mds-table-header-cell>
    <mds-table-header-cell label="Azioni"></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body>
    <mds-table-row>
      <mds-table-cell value="1">1</mds-table-cell>
      <mds-table-cell>Abbonamento annuale</mds-table-cell>
      <mds-table-cell value="120">120,00 EUR</mds-table-cell>
      <mds-table-cell><mds-button label="Modifica" tone="text" variant="primary"></mds-button></mds-table-cell>
    </mds-table-row>
    <mds-table-row>
      <mds-table-cell value="2">2</mds-table-cell>
      <mds-table-cell>Licenza mensile</mds-table-cell>
      <mds-table-cell value="15">15,00 EUR</mds-table-cell>
      <mds-table-cell><mds-button label="Modifica" tone="text" variant="primary"></mds-button></mds-table-cell>
    </mds-table-row>
  </mds-table-body>
</mds-table>

Providing Numeric Values for Correct Sort Order

When a column displays formatted text (currency, percentages) but should sort numerically, set the value prop on each <mds-table-cell> to the raw numeric string. The header cell reads value first and falls back to text content.

<mds-table>
  <mds-table-header>
    <mds-table-header-cell label="Prodotto"></mds-table-header-cell>
    <mds-table-header-cell label="Punteggio" sortable></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body>
    <mds-table-row>
      <mds-table-cell>Prodotto A</mds-table-cell>
      <mds-table-cell value="8.5">8,5 / 10</mds-table-cell>
    </mds-table-row>
    <mds-table-row>
      <mds-table-cell>Prodotto B</mds-table-cell>
      <mds-table-cell value="10">10 / 10</mds-table-cell>
    </mds-table-row>
    <mds-table-row>
      <mds-table-cell>Prodotto C</mds-table-cell>
      <mds-table-cell value="2.3">2,3 / 10</mds-table-cell>
    </mds-table-row>
  </mds-table-body>
</mds-table>

Setting the Direction from Outside

Set direction to sort by a column without a click - for example from a sort order kept in the address. It sorts the rows as the clicks that lead there would, resets the other columns to none, and the next click goes on with the cycle from it. none brings back the original order. No mdsTableHeaderCellSort is emitted: the application set it.

<mds-table>
  <mds-table-header>
    <mds-table-header-cell label="Data" sortable direction="descending"></mds-table-header-cell>
    <mds-table-header-cell label="Categoria" sortable></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body>
    <!-- rows -->
  </mds-table-body>
</mds-table>

document.querySelector('mds-table-header-cell').direction = 'none';

Sorting by the Back End

When the table shows one page of a larger set, give the table sorting="external" and each sortable column a sort-key. A click then moves no row: listen to mdsTableHeaderCellSort and load the rows in the order asked. See the pattern with mds-paginator in mds-table.

<mds-table sorting="external">
  <mds-table-header>
    <mds-table-header-cell label="Numero" sortable sort-key="number"></mds-table-header-cell>
    <mds-table-header-cell label="Ricevuta il" sortable sort-key="received"></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body>
    <!-- the rows of the current page -->
  </mds-table-body>
</mds-table>

document.querySelector('mds-table').addEventListener('mdsTableHeaderCellSort', (event) => {
  const { sortKey, direction } = event.detail; // 'received', 'descending'
  loadFirstPage(direction === 'none' ? undefined : { sortKey, direction });
});

Styling Customization

Target the label or action shadow parts for glyph-level overrides. Set them on the host or a parent selector.

mds-table-header-cell::part(label) {
  font-weight: var(--font-weight-semibold);
}