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

Minimal Ambient Background

The simplest and most common use: a full-bleed autoplaying video loop with no extra configuration needed, because autoplay, loop, and muted are all true by default.

<mds-video-wall src="/assets/video/ambient.mp4"></mds-video-wall>

Poster Image for Initial Frame

Supply a poster image so users see a meaningful still frame before the video loads, or on devices where autoplay is suppressed by the browser.

<mds-video-wall
  src="/assets/video/ambient.mp4"
  poster="/assets/video/ambient-preview.webp"
></mds-video-wall>

Noise Overlay for Texture

Add a grain overlay with noise to give the video a cinematic or retro feel. Choose the texture that fits the intended mood: classic, sharp, soft, or tv.

<!-- Subtle classic grain -->
<mds-video-wall src="/assets/video/ambient.mp4" noise="classic"></mds-video-wall>

<!-- High-contrast TV static -->
<mds-video-wall src="/assets/video/ambient.mp4" noise="tv"></mds-video-wall>

Foreground Content Overlay via the content Slot

Place any text, HTML elements, or Magma components in the content slot to render them centered above the video. The overlay wrapper is shown only while this slot is populated, also when the content is added after the first render, so an empty overlay never affects layout.

<mds-video-wall src="/assets/video/ambient.mp4" noise="soft">
  <div slot="content" class="text-on-inverse text-center">
    <mds-text typography="h1">Benvenuto in Magma</mds-text>
    <mds-button label="Scopri di piu" variant="primary" tone="strong"></mds-button>
  </div>
</mds-video-wall>

Browser Fallback via the Default Slot

The default (unnamed) slot is projected inside the native <video> element. Use it for the message displayed when the browser does not support video playback.

<mds-video-wall src="/assets/video/ambient.mp4">
  Il tuo browser non supporta la riproduzione video. Aggiorna il browser per continuare.
</mds-video-wall>

Disabling Autoplay with Controlled Preload

When the video should not play automatically - for example on a media showcase page - set autoplay and loop to false via a framework binding or a JS property assignment, and use preload to control how eagerly the file is fetched. Note: preload is ignored by the browser while autoplay is active.

<!--
  autoplay and loop default to true: turn them off with a framework
  property binding or the JS properties below.
  Do NOT write autoplay="false" in plain HTML - see antipattern.md.
-->
<mds-video-wall
  src="/assets/video/showcase.mp4"
  poster="/assets/video/showcase-preview.webp"
  preload="metadata"
></mds-video-wall>

// Disable autoplay and loop via JS property when not using a framework
const wall = document.querySelector('mds-video-wall');
wall.autoplay = false;
wall.loop = false;

CSS Customization via Documented Properties

Style the noise overlay and video fit only through the documented --mds-video-wall-* CSS custom properties. Set them on the host element or a parent selector, using the semantic color roles for mode-aware values.

/* Warm amber noise tint, contained fit for a non-16:9 source */
.hero-section mds-video-wall {
  --mds-video-wall-noise-background-color: rgb(var(--magma-warning-emphasis-hover) / 0.6);
  --mds-video-wall-noise-background-size: 4px;
  --mds-video-wall-video-fit: contain;
}