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

Plain Title in the Default Slot

The most common use: pass heading text (or a heading element) into the default slot to set the card’s title. The header arranges it in the card’s top region automatically.

<mds-card>
  <mds-card-header>
    <mds-text typography="h5">Dettagli account</mds-text>
  </mds-card-header>
  <mds-card-content>
    <mds-text>Contenuto principale della card.</mds-text>
  </mds-card-content>
</mds-card>

Header with Inline Action

Place one or more <mds-button> elements in the action slot when the header needs an inline control. The actions wrapper is only rendered when at least one element is assigned to this slot - omit the slot entirely when no actions are needed.

<mds-card>
  <mds-card-header>
    <mds-text typography="h5">Impostazioni notifiche</mds-text>
    <mds-button
      slot="action"
      icon="mi/baseline/edit"
      aria-label="Modifica impostazioni"
      variant="primary"
      tone="text"
    ></mds-button>
  </mds-card-header>
  <mds-card-content>
    <mds-text>Gestisci le preferenze di notifica.</mds-text>
  </mds-card-content>
</mds-card>

Header with Multiple Actions

Add multiple elements to the action slot when several inline controls are needed. They are rendered in the single actions region next to the header content.

<mds-card>
  <mds-card-header>
    <mds-text typography="h5">Documento di progetto</mds-text>
    <mds-button
      slot="action"
      label="Modifica"
      icon="mi/baseline/edit"
      variant="primary"
      tone="outline"
    ></mds-button>
    <mds-button
      slot="action"
      icon="mi/baseline/delete"
      aria-label="Elimina documento"
      variant="error"
      tone="text"
    ></mds-button>
  </mds-card-header>
  <mds-card-content>
    <mds-text>Specifiche tecniche rev. 3.</mds-text>
  </mds-card-content>
</mds-card>

Header with Supporting Text

Pass additional descriptive text below the title by wrapping title and text in one element in the default slot. The header lays its default-slot children out in a row, spread apart (justify-content: space-between), so two loose elements would sit side by side.

<mds-card>
  <mds-card-header>
    <div class="flex flex-col">
      <mds-text typography="h5">Report mensile</mds-text>
      <mds-text typography="caption">Aggiornato il 1 giugno 2026</mds-text>
    </div>
  </mds-card-header>
  <mds-card-content>
    <mds-text>Riepilogo delle attivita del mese.</mds-text>
  </mds-card-content>
</mds-card>

Full Card Composition

<mds-card-header> is designed to compose with the other card sub-parts. Each sub-part self-slots into its region; the card infers which regions are present and adjusts its layout accordingly.

<mds-card>
  <mds-card-media>
    <mds-img src="/images/copertina.jpg" alt="Copertina articolo"></mds-img>
  </mds-card-media>
  <mds-card-header>
    <mds-text typography="h4">Novita dal team</mds-text>
    <mds-button
      slot="action"
      icon="mi/baseline/share"
      aria-label="Condividi"
      variant="primary"
      tone="text"
    ></mds-button>
  </mds-card-header>
  <mds-card-content>
    <mds-text>Aggiornamenti sul rilascio di Magma 3.0.</mds-text>
  </mds-card-content>
  <mds-card-footer>
    <mds-button label="Leggi di piu" variant="primary" tone="strong"></mds-button>
  </mds-card-footer>
</mds-card>

Header Without a Title - Using the Action Slot Alone

When the card header exists only to host action controls and carries no title text, leave the default slot empty and place the controls in the action slot. The component renders just the actions container.

<mds-card>
  <mds-card-header>
    <mds-button
      slot="action"
      icon="mi/baseline/more-vert"
      aria-label="Altre opzioni"
      variant="dark"
      tone="text"
    ></mds-button>
  </mds-card-header>
  <mds-card-content>
    <mds-text>Scheda con solo azione nell'intestazione.</mds-text>
  </mds-card-content>
</mds-card>