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

Basic Media Region with mds-img

Place <mds-card-media> as a direct child of <mds-card>. No slot attribute is needed - the component self-assigns into the card’s media region. Put the visual asset in the default slot; mds-img is the recommended choice.

<mds-card>
  <mds-card-media>
    <mds-img src="/img/copertina.jpg" alt="Copertina articolo"></mds-img>
  </mds-card-media>
</mds-card>

Media with an Overlay Caption via the content Slot

Use the named content slot for text or controls that should float in front of the media asset. The overlay is absolutely positioned over the media, bottom-aligned and horizontally centered.

<mds-card>
  <mds-card-media>
    <mds-img src="/img/evento.jpg" alt="Evento annuale"></mds-img>
    <mds-text slot="content" typography="label">12 giugno 2026</mds-text>
  </mds-card-media>
</mds-card>

Media with an Overlay Action Control

The content slot accepts any element or component. Use it to place a badge, chip, or button on top of the media when the design calls for an interactive overlay.

<mds-card>
  <mds-card-media>
    <mds-img src="/img/prodotto.jpg" alt="Scheda prodotto"></mds-img>
    <mds-badge slot="content" label="Novita'" variant="info" tone="strong"></mds-badge>
  </mds-card-media>
</mds-card>

Card with All Regions Composed Together

<mds-card-media> composes alongside mds-card-header, mds-card-content, and mds-card-footer inside mds-card. Each region self-assigns its slot; the card drives the responsive layout automatically unless disable-auto-grid is set.

<mds-card>
  <mds-card-media>
    <mds-img src="/img/notizia.jpg" alt="Immagine della notizia"></mds-img>
  </mds-card-media>
  <mds-card-header>
    <mds-text typography="h6">Titolo della notizia</mds-text>
  </mds-card-header>
  <mds-card-content>
    <mds-text>Descrizione breve della notizia.</mds-text>
  </mds-card-content>
  <mds-card-footer>
    <mds-button label="Leggi di piu'" variant="primary" tone="text"></mds-button>
  </mds-card-footer>
</mds-card>

Video in the Default Slot

The default slot accepts any media element or component. Use a native <video> when the design calls for motion content rather than a still image.

<mds-card>
  <mds-card-media>
    <video src="/media/presentazione.mp4" autoplay muted loop playsinline></video>
  </mds-card-media>
</mds-card>

Styling the Overlay Part via ::part(content)

The content overlay div is exposed as the content shadow part. Use it for layout adjustments that the host’s positioning rules do not cover - for example, changing alignment or adding a gradient scrim. Set the style on the host or a parent selector; do not pierce shadow DOM with >>> or undocumented class names.

.card-destacada mds-card-media::part(content) {
  align-items: flex-start;
  background: linear-gradient(to top, rgb(var(--magma-backdrop-color) / 0.7), transparent);
  padding: calc(var(--spacing) * 600);
}