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

Basic Image with Alt Text

The canonical form. Always supply a meaningful alt value for content images - it doubles as the accessible name and as the visible label in both the error state and the deferred-load placeholder.

<mds-img src="/assets/img/copertina-corso.jpg" alt="Copertina del corso di formazione"></mds-img>

Responsive Image with srcset and sizes

Pass the standard srcset and sizes attributes exactly as you would on a native <img>. The browser picks the best source based on viewport and device pixel ratio.

<mds-img
  src="/assets/img/hero-800.jpg"
  srcset="/assets/img/hero-400.jpg 400w, /assets/img/hero-800.jpg 800w, /assets/img/hero-1600.jpg 1600w"
  sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1600px"
  alt="Vista panoramica del centro storico"
></mds-img>

Eager Loading for Above-the-Fold Images

loading defaults to "lazy". Set it to "eager" only for images that are immediately visible on page load, such as hero images or content at the top of the first screen.

<mds-img
  src="/assets/img/hero-principale.jpg"
  alt="Hero della pagina principale"
  loading="eager"
></mds-img>

Consumption-Aware Sources with srcset-consumption

Use srcset-consumption to serve a different image source depending on the user’s bandwidth preference stored via mds-pref-consumption. Tag each source with low, medium, or high. Under the low preference the image is deferred behind a “Carica immagine” placeholder until the user clicks.

<mds-img
  src="/assets/img/copertina-libro.jpg"
  srcset-consumption="/assets/img/copertina-bw-1x.jpg low, /assets/img/copertina-1x.jpg medium, /assets/img/copertina-2x.jpg high"
  alt="Il nuovo codice dei contratti pubblici"
></mds-img>

Consumption-Aware with Fallback src

Provide src alongside srcset-consumption as the fallback used when a bucket is missing from the consumption map. Here src is the high-resolution file; only low and medium buckets are overridden.

<mds-img
  src="/assets/img/copertina-2x.jpg"
  srcset-consumption="/assets/img/copertina-bw-1x.jpg low, /assets/img/copertina-1x.jpg medium"
  alt="Manuale pratico degli appalti pubblici"
></mds-img>

Reacting to Load Events

Listen to mdsImgLoadSuccess and mdsImgLoadError to react to image load outcomes. Both events carry the underlying HTMLImageElement in event.detail.image, allowing you to read natural dimensions or show fallback UI.

<mds-img
  id="hero"
  src="/assets/img/hero-principale.jpg"
  alt="Immagine principale"
></mds-img>

<script>
  document.getElementById('hero').addEventListener('mdsImgLoadSuccess', (event) => {
    const img = event.detail.image;
    console.log('Caricata:', img.naturalWidth, 'x', img.naturalHeight);
  });

  document.getElementById('hero').addEventListener('mdsImgLoadError', (event) => {
    console.warn('Immagine non disponibile:', event.detail.image.src);
  });
</script>

Fixed Dimensions

Set width and height (as string pixel values) to reserve layout space and prevent content reflow during load: they give the inner image its aspect ratio. They do not fix the rendered size - the inner image follows the host, which is display: flex; width: 100% by default - so size the host with CSS when a fixed pixel size is intended.

<mds-img
  src="/assets/img/thumbnail.jpg"
  alt="Anteprima documento"
  width="320"
  height="240"
></mds-img>

Styling Customization

Style the component through its documented --mds-img-* CSS custom properties. Use the semantic color roles wrapped in rgb(var(--magma-<role>)) so dark mode and high-contrast modes keep working.

.card-copertina mds-img {
  --mds-img-background: rgb(var(--magma-accent-emphasis-hover));
  --mds-img-color: rgb(var(--magma-accent-surface));
  --mds-img-icon-color: rgb(var(--magma-accent-border));
  --mds-img-error-background: rgb(var(--magma-danger-wash-base));
  --mds-img-error-color: rgb(var(--magma-danger-fg));
}

Styling the Inner <img> via ::part(media)

When a CSS property must be applied directly to the inner <img> element (for example object-fit or border-radius) use the documented media shadow part. This is the only supported way to pierce the shadow boundary.

.copertina-libro mds-img::part(media) {
  border-radius: var(--magma-radius-md);
  object-fit: cover;
}