Common incorrect uses of <mds-table-header>. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in agents/anti-patterns.md - they apply here too but are not repeated.

Do Not Use <mds-table-header> Outside <mds-table>

<mds-table-header> calls this.host.closest('mds-table') during load to wire up selection and action-column detection. Used standalone or inside a raw <table> it finds no table: the actions column is never detected, the master checkbox selects nothing, and every selection and sorting feature breaks.

<!-- INCORRECT -->
<table>
  <mds-table-header>
    <mds-table-header-cell label="Nome"></mds-table-header-cell>
  </mds-table-header>
</table>

<!-- CORRECT -->
<mds-table>
  <mds-table-header>
    <mds-table-header-cell label="Nome"></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body><!-- rows --></mds-table-body>
</mds-table>

Do Not Slot <mds-table-row> Inside <mds-table-header>

The default slot of <mds-table-header> expects <mds-table-header-cell> elements - one per column. Slotting <mds-table-row> (a body-row component) into the header produces broken layout and wrong ARIA roles.

<!-- INCORRECT -->
<mds-table>
  <mds-table-header>
    <mds-table-row>
      <mds-table-cell>Cognome</mds-table-cell>
      <mds-table-cell>Email</mds-table-cell>
    </mds-table-row>
  </mds-table-header>
  <mds-table-body><!-- rows --></mds-table-body>
</mds-table>

<!-- CORRECT -->
<mds-table>
  <mds-table-header>
    <mds-table-header-cell label="Cognome"></mds-table-header-cell>
    <mds-table-header-cell label="Email"></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body><!-- rows --></mds-table-body>
</mds-table>

Do Not Set selectable Directly on <mds-table-header>

selectable on the header is an internal prop driven by <mds-table> - when the table loads and whenever its selectable changes, it pushes its own value down. Setting it by hand on the header bypasses that synchronisation path and can leave rows and the master checkbox out of sync.

<!-- INCORRECT -->
<mds-table>
  <mds-table-header selectable>
    <mds-table-header-cell label="Utente"></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body><!-- rows --></mds-table-body>
</mds-table>

<!-- CORRECT -->
<mds-table selectable>
  <mds-table-header>
    <mds-table-header-cell label="Utente"></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body><!-- rows --></mds-table-body>
</mds-table>

Do Not Add a Manual “Actions” Header Cell

The component detects [slot="action"] children in the table body and appends the localized “Azione” header cell automatically. Adding your own header cell for actions doubles the column and misaligns the grid.

<!-- INCORRECT -->
<mds-table>
  <mds-table-header>
    <mds-table-header-cell label="Nome"></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>Mario Rossi</mds-table-cell>
      <mds-button slot="action" icon="mi/baseline/delete" title="Elimina" variant="error" tone="text"></mds-button>
    </mds-table-row>
  </mds-table-body>
</mds-table>

<!-- CORRECT -->
<mds-table>
  <mds-table-header>
    <mds-table-header-cell label="Nome"></mds-table-header-cell>
  </mds-table-header>
  <mds-table-body>
    <mds-table-row>
      <mds-table-cell>Mario Rossi</mds-table-cell>
      <mds-button slot="action" icon="mi/baseline/delete" title="Elimina" variant="error" tone="text"></mds-button>
    </mds-table-row>
  </mds-table-body>
</mds-table>

Do Not Call setSelection from Application Code

setSelection(selectedItems, totalItems) is an internal method called by <mds-table> after each row selection change. Calling it from application code duplicates the table’s internal bookkeeping and can leave the checkbox in an inconsistent state. React to selection results via the mdsTableSelectionChange event instead.

<!-- INCORRECT -->
<script>
  const header = document.querySelector('mds-table-header');
  header.setSelection(2, 5); // do not call this from app code
</script>

<!-- CORRECT -->
<script>
  document.querySelector('mds-table').addEventListener('mdsTableSelectionChange', (e) => {
    console.log('Selezione corrente:', e.detail.rows);
  });
</script>

Do Not Use Raw <thead> / <th> Instead of the Component

Mixing raw HTML table elements with the Magma compound disrupts the selection wiring, the automatic actions column, and the localized labels that <mds-table-header> provides.

<!-- INCORRECT -->
<mds-table>
  <thead>
    <tr>
      <th>Nome</th>
      <th>Email</th>
    </tr>
  </thead>
  <mds-table-body><!-- rows --></mds-table-body>
</mds-table>

<!-- CORRECT -->
<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>
  <mds-table-body><!-- rows --></mds-table-body>
</mds-table>