Skip to content

ReferenceMedia

background-video

Decorative background video element with automatic muting and looping

Decorative background video for a source the browser can play natively. By default it’s muted, looped, and autoplaying.

<background-video> renders a <video> inside shadow DOM and fills the box you give the component. Use the opt-out attributes in the API to change its playback defaults.

An HLS URL only works where the browser has native HLS playback. See Add a background video to choose a cross-browser HLS or Mux path and set up layout, poster, and decorative semantics.

Import

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

Or load it from the CDN:

<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/background-video.js"></script>

Examples

Basic Usage

<div class="container">
  <background-video src="https://stream.mux.com/601n4w1fq88NJiVpzvrQQeQfNnnjjfKMIN7dCGAEarTs/highest.mp4"></background-video>
</div>

API

Attributes

Attribute Description
src URL of a video the browser can play directly, such as an MP4 or WebM file
nomuted Turns off muting
noloop Turns off looping
noautoplay Turns off autoplay
crossorigin, preload, controls, controlslist Passed through to the inner video

An explicit muted, loop, or autoplay attribute wins over its opt-out. Opt-outs and passed-through attributes also apply when set or changed after the element is created.

Properties

Property Description
src URL of the video. Assigning a new one restarts playback
error The inner video’s MediaError, or null
target Inner native <video> element. Call play() and pause() on it

The element also fires an error event when the inner video does.

Styling

Custom property Default Description
--media-object-fit inherit How the video fits its box
--media-object-position 50% 50% Position of the video within its box

Set an explicit size on the custom element or an author-owned wrapper.