Skip to content

ReferencePresets

Background preset

The background video preset — a player, feature bundle, skin, and media for ambient video with no controls

@videojs/html/background is the preset for ambient background video with no user controls. It bundles the <background-video-player> element, the backgroundFeatures bundle it is configured with, one chrome-less skin, and the <background-video> media component, which autoplays, mutes, and loops. See Presets for how presets fit together and Background video for building one.

Import

import '@videojs/html/background/player';
import '@videojs/html/background/skin';
import '@videojs/html/background/video';

Or load the CDN bundle that registers all three:

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

Unlike the other presets, the background preset has one bundle and no player-only bundle.

Usage

<script type="module">
  import '@videojs/html/background/player';
  import '@videojs/html/background/skin';
  import '@videojs/html/background/video';
</script>

<background-video-player>
  <background-video-skin>
    <background-video src="hero.mp4"></background-video>
  </background-video-skin>
</background-video-player>

Player

@videojs/html/background/player registers <background-video-player>, whose class is BackgroundVideoPlayerElement. It is a player element created by createPlayer with backgroundFeatures. It owns the player store but no layout. Put the skin or a <media-container> inside it.

Attribute Property Description
keep-alive — Keeps the player and its store alive when the element leaves the DOM. Call destroy() when you’re done with it.

The bundle has no feature that takes player inputs, so the element has no player-input attributes such as content-title or poster; keep-alive is the only attribute it reads. Its read-only store property returns its player store.

The preset root also exports a PlayerController bound to the background player’s store. Use it from any custom element inside <background-video-player>; see PlayerController.

Feature bundle

backgroundFeatures is the array of features the player is configured with. The background media component handles autoplay, muting, and looping on its own:

backgroundFeatures is currently empty, so the player's store holds no feature state or actions.

Its type, BackgroundFeatures, is the matching empty tuple. Import it from the package root:

import type { BackgroundFeatures } from '@videojs/html';

To add a feature, pass your own array to createPlayer. For example, add playback to drive a play button over the background video:

import { createPlayer, playbackFeature } from '@videojs/html';
import { backgroundFeatures } from '@videojs/html/background';

const { PlayerElement } = createPlayer({
  features: [...backgroundFeatures, playbackFeature],
});

customElements.define('my-background-player', PlayerElement);

Skins

  • BackgroundVideoSkin — the only skin, a chrome-less surface that sizes the video and renders no controls.

Media

@videojs/html/background/video registers <background-video>, which renders a <video> inside shadow DOM that is muted, looped, and autoplaying by default. It is the same registration as @videojs/html/media/background-video. For HLS or Mux sources, use <hls-background-video> or <mux-background-video> instead.

Exports

The preset root, @videojs/html/background, has no side effects. Importing it never registers an element:

Export Description
BackgroundVideoPlayerElement The player element class.
PlayerController The player controller, bound to the background player’s store.
backgroundFeatures The feature bundle.
BackgroundVideoSkinElement The skin element class.

Registration entry points are side-effect-only:

Entry point Registers
@videojs/html/background/player <background-video-player>
@videojs/html/background/skin <background-video-skin> and <media-container>
@videojs/html/background/video <background-video>