📺 Youtube Background

ESM / jQuery plugin for turning a YouTube, Vimeo or plain video file link into a cover background — with autoplay, looping, play/mute controls, seek bars and playlist groups.

npm install youtube-background

Live demos

Every band below is a real instance. The markup that produces it is right under it.

YouTube

Autoplaying, muted, looping, and paused whenever it scrolls out of view.

<div data-vbg="https://www.youtube.com/watch?v=eEpEeyqGlxA" data-vbg-load-background="true"></div>

A slice of a video

start-at skips the intro, end-at keeps the loop short. The play button is the plugin's own.

<div
  data-vbg="https://www.youtube.com/watch?v=MgDZBqTuUuE"
  data-vbg-play-button="true"
  data-vbg-start-at="10"
  data-vbg-end-at="16"
></div>

Sound, and your own controls

Unmute with the plugin's button, or drive it from buttons of your own.

Vimeo

Same attributes, different platform. Unlisted links keep their hash.

<div data-vbg="https://vimeo.com/137250145" data-vbg-mute-button="true"></div>
<!-- unlisted -->
<div data-vbg="https://vimeo.com/304887422/34c51f7a09"></div>

A plain video file

Any .mp4, .webm, .ogg, .avi, .mov, .m4v or .qt URL, played in a native <video>.

A group

Three backgrounds across all three source types, played as one playlist.

Usage

Point an empty element at a video and initialise. Without jQuery:

import { VideoBackgrounds } from "youtube-background";

new VideoBackgrounds("[data-vbg]");

With jQuery:

jQuery("[data-vbg]").youtube_background();

Or from a script tag, where the plugin exposes window.VideoBackgrounds and, once initialised through jQuery, window.VIDEO_BACKGROUNDS:

<script src="jquery.youtube-background.min.js"></script>

The seek bars, play/mute toggles and group controls used above live in a separate experimental bundle:

<script src="youtube-background-experimental.min.js"></script>

Options

Every option is settable as a data-vbg-* attribute on the element, or as a key in the object passed to the constructor. Attributes win.

Option	Default	What it does
`autoplay`	`true`	Start as soon as the element is in view
`muted`	`true`	Start muted — required for autoplay to be allowed
`loop`	`true`	Restart when the video ends
`mobile`	`true`	Create the background on mobile too
`always-play`	`false`	Keep playing while off-screen
`start-at`	`0`	Seconds to start from
`end-at`	`0`	Seconds to stop at, `0` for the full duration
`volume`	`1`	`0`–`1`, applied on first unmute
`play-button`	`false`	Render the plugin's play/pause toggle
`mute-button`	`false`	Render the plugin's mute toggle
`poster`	`null`	Image shown until the first frame plays
`load-background`	`false`	Use the platform's own thumbnail as the poster
`resolution`	`'16:9'`	Aspect ratio used to cover the container
`fit-box`	`false`	Stretch to the container instead of covering it
`inline-styles`	`true`	Let the plugin write the positioning styles
`no-cookie`	`true`	Use the privacy-preserving embed domains
`lazyloading`	`false`	Add `loading="lazy"` to the player
`title`	`'Video background'`	Accessible name for the player frame

Events

Every instance dispatches on its own element and bubbles:

video-background-ready, video-background-play, video-background-pause, video-background-ended, video-background-seeked, video-background-time-update, video-background-state-change, video-background-mute, video-background-unmute, video-background-volume-change, video-background-resize, video-background-destroyed.

document.querySelector("#hero").addEventListener("video-background-ready", (event) => {
  console.log(event.detail.type, event.detail.currentState);
});

API

const backgrounds = new VideoBackgrounds("[data-vbg]");

const instance = backgrounds.get(document.querySelector("#hero"));
instance.play();
instance.pause();
instance.mute();
instance.unmute();
instance.setVolume(0.4);
instance.seek(50);          // percent
instance.seekTo(12);        // seconds
instance.setSource("https://vimeo.com/137250145");

backgrounds.pauseAll();
backgrounds.playAll();
backgrounds.add(element);
backgrounds.destroy(element);
backgrounds.destroyAll();