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 optionsHow 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
.m3u8URL 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. The streaming variations below pause and play through the sametargetproperty. - 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:
The primary example works unchanged with the streaming elements: replace <background-video> with <hls-background-video> or <mux-background-video>, keep noautoplay, and update the selector in the script. Like <background-video>, they expose the native video as target for play() and pause(). Pausing keeps the stream and its position, so motion resumes where it stopped. To stop network activity as well, remove the element instead. Without keep-alive, removal releases the engine.
Play an HLS video
<hls-background-video> plays an HLS video without adding controls, audio, or captions. Pass a complete HLS URL through src:
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.
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.