Add a muted, looping background video to your web app with the Video.js Mux background video component. Use it for hero sections and decorative video that plays behind your content.
Video.js includes a background video component for Mux streams: the <mux-background-video> custom element for HTML and the MuxBackgroundVideo component for React. It plays a Mux HLS URL muted, looped, inline and on autoplay, with no controls, audio or captions, so it fits hero sections and other decorative video.
The Video.js background video guide is the source of truth for this component. It covers layout, posters, accessibility and the other background video options. This page gets a Mux background video running and covers the Mux-specific parts.
Using @mux/mux-background-video?
The standalone @mux/mux-background-video package is legacy. Existing integrations keep working, but new projects should use Video.js. See Migrate from @mux/mux-background-video.
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10/media/mux-background-video.js"></script>
<style>
.hero {
position: relative;
min-height: 480px;
}
.hero-media {
position: absolute;
inset: 0;
pointer-events: none;
}
.hero-media img,
.hero-media mux-background-video {
position: absolute;
inset: 0;
width: 100%;
height: 100%;
object-fit: cover;
--media-object-fit: cover;
}
.hero-content {
position: relative;
}
</style>
<section class="hero">
<div class="hero-media" aria-hidden="true">
<img src="https://image.mux.com/{PLAYBACK_ID}/thumbnail.webp?time=0" alt="" />
<mux-background-video
src="https://stream.mux.com/{PLAYBACK_ID}.m3u8"
crossorigin="anonymous"
></mux-background-video>
</div>
<div class="hero-content">
<h1>Your headline</h1>
</div>
</section>Replace {PLAYBACK_ID} with a playback ID from one of your Mux assets.
src. The component doesn't take a playback ID or a source object.<img> with an empty alt behind the video, as in the example, so something shows while the video loads.aria-hidden="true", because both are decorative. Keep your headings, links and buttons outside that wrapper.--media-object-fit: cover on <mux-background-video>. In React, the component renders a native <video>, so style it with className or style.The HTML example loads Video.js from a CDN. To install it with npm instead, run npm install @videojs/html @videojs/spf and import '@videojs/html/media/mux-background-video';.
The component chooses one rendition when playback starts, the largest that fits the screen, and doesn't switch renditions afterwards. To keep it from loading more than your layout needs, add a max_resolution parameter to the URL:
<mux-background-video
src="https://stream.mux.com/{PLAYBACK_ID}.m3u8?max_resolution=720p"
crossorigin="anonymous"
></mux-background-video>Mux leaves renditions above the cap out of the manifest. See Control playback resolution for the supported values.
Persistent background motion can distract or harm some viewers. WCAG 2.2.2 (Pause, Stop, Hide) asks that viewers can stop moving content that plays for more than five seconds. Give them a button to stop the video, and don't play it when the browser reports prefers-reduced-motion: reduce.
Turn off autoplay with noautoplay in HTML or autoPlay={false} in React, then start the video from your script once you've checked the motion preference. To control playback, call play() and pause() on the native <video> inside the component. In HTML, the element exposes it as its target property. In React, ref gives you the rendered <video>. Pausing keeps the stream and its position, so the video resumes where it stopped.
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10/media/mux-background-video.js"></script>
<section class="hero">
<div class="hero-media" aria-hidden="true">
<img src="https://image.mux.com/{PLAYBACK_ID}/thumbnail.webp?time=0" alt="" />
<mux-background-video
src="https://stream.mux.com/{PLAYBACK_ID}.m3u8"
crossorigin="anonymous"
noautoplay
></mux-background-video>
</div>
<div class="hero-content">
<h1>Your headline</h1>
<button type="button" id="motion-toggle">Play background video</button>
</div>
</section>
<script type="module">
// The native <video> inside the component.
const video = document.querySelector('mux-background-video').target;
const button = document.querySelector('#motion-toggle');
const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
function setMotion(enabled) {
if (enabled) {
video.play().catch(() => setMotion(false));
} else if (!video.paused) {
video.pause();
}
button.textContent = enabled ? 'Pause background video' : 'Play background video';
}
button.addEventListener('click', () => setMotion(video.paused));
reducedMotion.addEventListener('change', () => setMotion(!reducedMotion.matches));
setMotion(!reducedMotion.matches);
</script>Put the button outside the aria-hidden wrapper, so keyboard and screen reader users can reach it.
If the video communicates information, it isn't a background video. Use a Video.js player with controls and an accessible name instead.
The component doesn't send data to Mux Data on its own. To track views, attach mux-embed to the native <video> element inside the component:
target property.ref gives you the rendered <video>.<script src="https://cdn.jsdelivr.net/npm/mux-embed@5"></script>
<mux-background-video
id="hero-video"
src="https://stream.mux.com/{PLAYBACK_ID}.m3u8"
crossorigin="anonymous"
></mux-background-video>
<script type="module">
const element = document.querySelector('#hero-video');
mux.monitor(element.target, {
data: {
env_key: 'ENV_KEY',
player_name: 'Hero background video',
player_init_time: Date.now(),
video_title: 'Homepage hero',
},
});
</script>Replace ENV_KEY with the environment key from the Mux Dashboard. See Monitor the HTML5 video element for the other metadata fields.
The Video.js component keeps the <mux-background-video> tag name and the MuxBackgroundVideo export name, so most code only needs a new import. Change the package:
| Legacy | Video.js |
|---|---|
npm install @mux/mux-background-video | npm install @videojs/html @videojs/spf |
import '@mux/mux-background-video/html' | import '@videojs/html/media/mux-background-video' |
https://cdn.jsdelivr.net/npm/@mux/mux-background-video/html/+esm | https://cdn.jsdelivr.net/npm/@videojs/cdn@10/media/mux-background-video.js |
npm install @mux/mux-background-video (React) | npm install @videojs/react @videojs/spf |
import { MuxBackgroundVideo } from '@mux/mux-background-video/react' | import { MuxBackgroundVideo } from '@videojs/react/media/mux-background-video' |
Then update the attributes and props. Only src carries over:
| Legacy attribute (prop) | Video.js |
|---|---|
src | src, unchanged. Pass the complete Mux HLS URL. |
max-resolution (maxResolution) | Removed. Add ?max_resolution=720p to the src URL instead. See Limit the resolution. |
audio | Removed. The component is always muted and doesn't load audio. For video with sound, use a Video.js player. |
preload | Removed. The component starts loading as soon as it has a src. |
Mux Data through the mux-embed script | No longer automatic. Call mux.monitor on the inner video. See Monitor with Mux Data. |
A few behaviors also changed:
<img> as its poster. In React, MuxBackgroundVideo now renders its children inside the native <video>, where they don't show. In both HTML and React, move the poster next to the component inside the decorative wrapper, as in the quick start.noautoplay in HTML or autoPlay={false} in React. Call play() and pause() on the native video: the target property in HTML, or ref in React. See Let viewers stop the motion.error event and exposes error when the stream can't play. In React, use onError.For the full API, see the Video.js reference for <mux-background-video> (HTML) and MuxBackgroundVideo (React).