GuidePlayback

Add a background video

Add an accessible background video from an MP4, WebM, HLS, or Mux source

Add a decorative video behind your page content. Start with an MP4 or WebM file, which browsers can play directly. If your video is delivered as HLS, use the HLS or Mux option below.

Recommended approach

Use <background-video> with an MP4 or WebM URL. Put the video and poster inside a wrapper with aria-hidden="true" because both are decorative. Keep the heading, links, and other page content outside that wrapper.

Build the next great video experience

Compare source options

<section class="add-background-video-html-demo">
  <div class="add-background-video-html-demo__visual" aria-hidden="true">
    <img class="add-background-video-html-demo__poster" src="https://image.mux.com/601n4w1fq88NJiVpzvrQQeQfNnnjjfKMIN7dCGAEarTs/thumbnail.webp" alt="" />
    <background-video
      class="add-background-video-html-demo__media"
      src="https://stream.mux.com/601n4w1fq88NJiVpzvrQQeQfNnnjjfKMIN7dCGAEarTs/highest.mp4"
      noautoplay
    ></background-video>
  </div>
  <div class="add-background-video-html-demo__content">
    <h3>Build the next great video experience</h3>
    <a href="#common-variations">Compare source options</a>
    <button type="button" class="add-background-video-html-demo__motion-toggle" data-motion-toggle>
      Show background motion
    </button>
  </div>
</section>

.add-background-video-html-demo {
  position: relative;
  display: grid;
  min-height: 18rem;
  overflow: hidden;
  color: white;
  background: black;
  border-radius: 0.5rem;
  isolation: isolate;
}

.add-background-video-html-demo__visual,
.add-background-video-html-demo__poster,
.add-background-video-html-demo__media {
  position: absolute;
  inset: 0;
  width: 100%;
  height: 100%;
}

.add-background-video-html-demo__visual {
  pointer-events: none;
}

.add-background-video-html-demo__visual::after {
  position: absolute;
  inset: 0;
  content: "";
  background: linear-gradient(90deg, rgb(0 0 0 / 85%), rgb(0 0 0 / 55%));
}

.add-background-video-html-demo__poster,
.add-background-video-html-demo__media {
  display: block;
  object-fit: cover;
}

.add-background-video-html-demo__media {
  --media-object-fit: cover;
  --media-object-position: center;
}

.add-background-video-html-demo__content {
  position: relative;
  z-index: 1;
  display: grid;
  gap: 1rem;
  place-content: end start;
  max-width: 28rem;
  padding: 2rem;
}

.add-background-video-html-demo__content h3 {
  margin: 0;
  font-size: 1.75rem;
  line-height: 1.1;
}

.add-background-video-html-demo__content a,
.add-background-video-html-demo__motion-toggle {
  width: fit-content;
  padding: 0.625rem 1rem;
  color: black;
  text-decoration: none;
  font: inherit;
  cursor: pointer;
  border: 0;
  background: white;
  border-radius: 0.25rem;
}

.add-background-video-html-demo__content a:focus-visible,
.add-background-video-html-demo__motion-toggle:focus-visible {
  outline: 0.2rem solid white;
  outline-offset: 0.2rem;
}

.add-background-video-html-demo:not([data-motion-enabled]) .add-background-video-html-demo__media {
  display: none;
}

@media (prefers-reduced-motion: reduce) {
  .add-background-video-html-demo__media,
  .add-background-video-html-demo__motion-toggle {
    display: none;
  }
}

import '@videojs/html/media/background-video';

const initializedDemos = new WeakSet<HTMLElement>();

function initializeDemos(): void {
  document.querySelectorAll<HTMLElement>('.add-background-video-html-demo').forEach((hero) => {
    if (initializedDemos.has(hero)) return;

    initializedDemos.add(hero);

    const video = hero.querySelector('background-video')!.target!;
    const button = hero.querySelector<HTMLButtonElement>('[data-motion-toggle]')!;
    const preference = window.matchMedia('(prefers-reduced-motion: reduce)');
    let motionRequest = 0;

    function setMotion(enabled: boolean) {
      const request = ++motionRequest;

      hero.toggleAttribute('data-motion-enabled', enabled);
      button.textContent = enabled ? 'Hide background motion' : 'Show background motion';

      if (enabled) {
        video.play().catch(() => {
          if (request === motionRequest) setMotion(false);
        });
      } else {
        video.pause();
      }
    }

    const syncPreference = () => setMotion(!preference.matches);

    button.addEventListener('click', () => setMotion(!hero.hasAttribute('data-motion-enabled')));
    preference.addEventListener('change', syncPreference);
    document.addEventListener(
      'astro:before-swap',
      () => {
        preference.removeEventListener('change', syncPreference);
        setMotion(false);
      },
      { once: true }
    );
    syncPreference();
  });
}

initializeDemos();
document.addEventListener('astro:page-load', initializeDemos);

How it works

<background-video> renders a native <video> with muted, looping, inline playback. The example disables its default autoplay with noautoplay and starts playback after checking the motion preference. Its target property exposes the native video for play() and pause(). The decorative wrapper contains the video and an empty-alt poster; it is hidden from assistive technology and ignores pointer input.

The page defines the hero’s size. The video fills that space with --media-object-fit: cover, while the poster stays behind it. The motion button pauses and hides the video, revealing the poster. It sits outside the decorative wrapper so keyboard and screen-reader users can operate it.

When prefers-reduced-motion is active, the script pauses playback and the CSS hides the video and motion button. CSS hiding alone does not stop playback. If the browser rejects play(), the example keeps the poster visible.

Set size, position, and transforms on the decorative wrapper so the poster and video stay together.

Availability and constraints

Use a source the browser can play directly, such as MP4 or WebM.
Safari can play HLS URLs directly. Other browsers cannot do so reliably, so use an HLS variation below when the same .m3u8 URL must work across browsers.
<background-video> does not create a poster or report analytics. Keep the poster in your page and add analytics only when you need them.
Provide a way to pause or hide persistent background motion. The example includes that control and follows prefers-reduced-motion. For the streaming variations below, stop and restart motion by adding and removing the element.
If the video communicates information, remove aria-hidden, give it an accessible name and controls, and use a regular video player.

Common variations

Choose a variation based on the source you already have:

Need	Use
Cross-browser HLS with a small background-only player	`<hls-background-video>`
The same background-only player for a Mux HLS URL	`<mux-background-video>`

These streaming background components always autoplay. They ignore autoPlay={false} and noautoplay.

Keep the poster and motion button from the primary example. Change setMotion to create and append a streaming element only when motion is enabled, and remove it when motion is disabled. Do not set keep-alive: removal must destroy playback. Create a new element each time motion is enabled; do not reuse the removed one. These elements expose the inner video as video, rather than the native background element’s target.

Play an HLS video

<hls-background-video> plays an HLS video without adding controls, audio, or captions. Pass a complete HLS URL through src:

pnpm add @videojs/html @videojs/spf

<script type="module">
  import '@videojs/html/media/hls-background-video';
</script>

<hls-background-video
  class="hero-media"
  src="https://media.example.com/hero.m3u8"
  crossorigin
></hls-background-video>

Your HLS stream must be unencrypted and use fragmented MP4 video segments, also called fMP4 or CMAF. The component chooses one video size when playback starts and does not switch sizes later. It cannot play older MPEG-TS segments.

Play a Mux HLS URL

<mux-background-video> is a Mux-named alias for <hls-background-video>. Pass a complete Mux HLS URL, not a bare playback ID or source object:

It uses the same @videojs/spf installation shown for <hls-background-video> above.

<script type="module">
  import '@videojs/html/media/mux-background-video';
</script>

<mux-background-video
  class="hero-media"
  src="https://stream.mux.com/PLAYBACK_ID.m3u8?max_resolution=720p"
  crossorigin
></mux-background-video>

This component does not create a Mux poster, preview thumbnails, or analytics session. Keep the poster in your page and add analytics separately when you need them.

Troubleshooting

An HLS URL works in Safari but not another browser

<background-video> hands its src to the browser’s <video> element. Use <hls-background-video> for a supported fMP4 HLS source, or <mux-background-video> for a Mux HLS URL.

The video does not fill or follow transforms

Set the size, transforms, and measurements on the wrapper that contains the video and poster. Size the background-video component to fill that wrapper.

No poster or Mux analytics appear

The background-video components do not provide them. Render an empty-alt poster in the same wrapper as the video, and add analytics separately.

Components

Guides

Add a poster and loading placeholderSet the image shown before playback, then add a lightweight placeholder while it loads