Use Youtube/Vimeo/HTML5 Videos As A Fullscreen Background - youtube-background.js

File Size: 97.6 KB
Views Total: 22530
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   
Use Youtube/Vimeo/HTML5 Videos As A Fullscreen Background - youtube-background.js

Yet another jQuery/Vanilla JS Video Background plugin which makes Youtube/Vimeo/HTML5 videos behavior like a covering background.

Fully responsive and automatically adjusts the aspect ratio to fit the screen size after the viewport changed.

How to use it:

1. To use the plugin, include the JavaScript jquery.youtube-background.js after the latest jQuery library (OPTIONAL).

<!-- jQuery Is Optional -->
<script src="/path/to/cdn/jquery.slim.min.js"></script>
<!-- Core JS -->
<script src="/path/to/jquery.youtube-background.js"></script>

2. Embed a Youtube, Vimeo, or HTML5 video into the document by insert the video URL in the data-vbg attribute:

<div data-vbg="https://www.youtube.com/watch?v=IFSp2-CmQvk"></div>

3. Call the function to make the Youtube video fullscreen and act as a background. That's it.

// jQuery
$(function(){
  jQuery('[data-vbg]').youtube_background();
  // OPTIONAL
  const videoBackgrounds = VIDEO_BACKGROUNDS;
});

// Vanilla JavaScript
const videoBackgrounds = new VideoBackgrounds('[data-vbg]');

4. Auto disable the video background on the mobile. Default: false.

$(function(){
  jQuery('[data-vbg]').youtube_background({
    'mobile': true
  });
});

5. Display Play & Mute button on the Video. Default: false.

$(function(){
  jQuery('[data-vbg]').youtube_background({
    'play-button': true,
    'mute-button': true
  });
});

6. Determine whether to load and display the video cover as the background before loading the Youtube video player. Default: true.

$(function(){
  jQuery('[data-vbg]').youtube_background({
    'load-background': false
  });
});

7. Determine whether to auto play the video on page load. Default: true.

$(function(){
  jQuery('[data-vbg]').youtube_background({
    'autoplay': false
  });
});

8. Determine whether the video should be muted on page load. Default: true.

$(function(){
  jQuery('[data-vbg]').youtube_background({
    'muted': false
  });
});

9. Determine whether to loop the video. Default: true.

$(function(){
  jQuery('[data-vbg]').youtube_background({
    'loop': false
  });
});

10. Determine the resolution of the video. Default: '16:9'.

$(function(){
  jQuery('[data-vbg]').youtube_background({
    'resolution': '16:9'
  });
});

11. Determine the offset in pixels. Useful to enlarge the video to hide the info elements. Default: '200'.

$(function(){
  jQuery('[data-vbg]').youtube_background({
    'offset': 200
  });
});

12. Determine whether or not to set the player iframe to fit the container. Default: false.

$(function(){
  jQuery('[data-vbg]').youtube_background({
    'fit-box': true
  });
});

13. Enable/disable inline styles from the iframe and wrapper. Default: true.

$(function(){
  jQuery('[data-vbg]').youtube_background({
    'inline-styles': true
  });
});

14. Set in seconds when the background video will start & end. Default: 0.

$(function(){
  jQuery('[data-vbg]').youtube_background({
    'start-at': 2,
    'end-at': 0
  });
});

15. Determine whether to auto stop playing. Default: false.

$(function(){
  jQuery('[data-vbg]').youtube_background({
    always-play: false,
  });
});

16. Set the initial volume. Default: 1.

$(function(){
  jQuery('[data-vbg]').youtube_background({
    volume: 0.6
  });
});

17. Determine whether to disable cookies. Default: true.

$(function(){
  jQuery('[data-vbg]').youtube_background({
    no-cookie: false,
  });
});

18. Force autoplay on battery saver mode on user first interaction. Default: false.

$(function(){
  jQuery('[data-vbg]').youtube_background({
    force-on-low-battery: true,
  });
});

19. Determine whether to lazy load the iframe/video. Default: false.

$(function(){
  jQuery('[data-vbg]').youtube_background({
    lazyloading: true,
  });
});

20. Override the default poster image. Default: null.

$(function(){
  jQuery('[data-vbg]').youtube_background({
    'poster': '/path/to/poster/image/',
  });
});

21. You're also allowed to pass the options via HTML data-vbg-* attributes:

  • data-vbg-play-button
  • data-vbg-mute-button
  • data-vbg-autoplay
  • data-vbg-mooted
  • data-vbg-loop
  • data-vbg-mobile
  • data-vbg-load-background
  • data-vbg-resolution
  • data-vbg-offset
  • data-vbg-fit-box
  • data-vbg-inline-styles
  • data-vbg-start-at
  • data-vbg-end-at
  • data-vbg-always-play
  • data-vbg-volume
  • data-vbg-no-cookie
  • data-vbg-force-on-low-battery
  • data-vbg-lazyloading
  • data-vbg-poster
<div data-vbg-play-button="true" data-vbg="https://www.youtube.com/watch?v=IFSp2-CmQvk"></div>

22. Event handlers.

// Vanilla JavaScript
document.querySelector('[data-vbg]').addEventListener('EVENT-NAME', function(event) {
  // ...
});

// jQuery
$('[data-vbg]').on('EVENT-NAME', function(event) {
  // ...
});

// All Events
$('[data-vbg]').on('video-background-time-update', function(event) {
  // ...
});

$('[data-vbg]').on('video-background-state-change', function(event) {
  // ...
});

$('[data-vbg]').on('video-background-play', function(event) {
  // ...
});

$('[data-vbg]').on('video-background-pause', function(event) {
  // ...
});

$('[data-vbg]').on('video-background-ended', function(event) {
  // ...
});

$('[data-vbg]').on('video-background-mute', function(event) {
  // ...
});

$('[data-vbg]').on('video-background-unmute', function(event) {
  // ...
});

$('[data-vbg]').on('video-background-volume-change', function(event) {
  // ...
});

$('[data-vbg]').on('video-background-resize', function(event) {
  // ...
});

$('[data-vbg]').on('video-background-destroyed', function(event) {
  // ...
});

23. API methods.

// get the element
const instanceElement = document.querySelector('[data-vbg]');

// get the instance by UID
const instance = videoBackgrounds.get(instanceElement);

instance.play();

instance.pause();

instance.mute();

instance.unmute();

instance.setSource('https://www.youtube.com/watch?v=VIDEO-ID');

instance.setVolume(0.5);

instance.getVolume(); 

instance.seek(25);

instance.seekTo(1.25);

instance.setStartAt(10);

instance.setEndAt(20);

24. Properties.

// true if playing
instance.playing

// true if muted
instance.muted

// true if the video is intersecting the viewport
instance.isIntersecting 

// current state 
instance.currentState

// current time of the video in seconds
instance.currentTime

// percentage of the video that has been played
instance.percentComplete

// the element that the video background is attached to
instance.element

// the element of the video player
instance.playerElement 

// the video player object
instance.player

// the type of the video
instance.type

// volume of the video
instance.volume

Changelog:

v1.1.6 (2024-02-24)

  • Support for Vimeo unlisted links reporded

v1.1.5 (2024-02-07)

  • Minimal update of the experimental controls feature - VideoBackgroundGroup. 
  • Fixed the issue where video was played by force without checking if it's visible and autoplayable. 
  • Added states to the groups

v1.1.4 (2024-01-27)

  • Bugfix

v1.1.3 (2024-01-17)

  • Moved experimental features to new files.
  • Bugfixes.

v1.1.2 (2023-11-27)

  • Grouping video backgrounds

v1.1.1 (2023-11-16)

  • Fixed the properties parsing when you pass properties as an object.
  • Fixed backwards compatibility issues back to Safari 10.

v1.1.0 (2023-11-09)

  • Update

v1.0.22 (2023-11-07)

  • Update

v1.0.21 (2023-11-03)

  • Fixed a vimeo blooper for setting start and end time. correct implementation of the resize observer. some work on reducing the reduncancy.

v1.0.20 (2023-11-02)

  • Add support for regular videos.
  • Fix bugs.

v1.0.19 (2023-10-27)

  • Vimeo iFrame API is no longer a part of the script, but it loads only if vimeo video is detected
  • Fixed the issue with maxresdefault.jpg for youtube thumbnail
  • Try catched intersection errors when player is not loaded yet

v1.0.18 (2023-10-26)

  • Adds the volume setting and a global variable for the index VIDEO_BACKGROUNDS when jQuery is being used, so one can access and update the volume programatically.
  • Fixed an issue where some residue code remained for Vimeo which was throwing an error when trying to set Vimeo poster
  • Vimeo also got the option load-background, where the background will be loaded via https://vumbnail.com
  • load-background is set to false by default, responsive image element is prefered for the background which improves performance of the page
  • no-cookie option added which is enabled by default. This forces Youtube and Vimeo not to track you with cookies
  • Youtube iFrame API script is loaded only once now and only if there is a Youtube video, requested in #43
  • Various found improvements

v1.0.17 (2023-10-26)

  • Pause the videos when not visible

v1.0.16 (2023-10-26)

  • Vimeo background now has play/pause mute/unmute controls and start-at/end-at properties just like youtube backgrounds

v1.0.15 (2023-10-13)

  • fix cdn references

v1.0.14 (2022-01-16)

  • Very minor update: If the parent element is position absolute, fixed, sticky or relative, don't add the inline rule position: relative.

v1.0.13 (2021-12-16)

  • Removed experimental feature ActivityMonitor from the build.

v1.0.12 (2021-12-15)

  • Added partial support for Vimeo videos
  • Added partial support for HTML5 videos
  • Added optional ResizeObserver for recalculating video resolution and placement on resize of the containing element
  • Next to data-youtube and data-ytbg-, it now accepts data-vbg and data-vbg- attributes, this is a next step to transition this code to a more generalized version

v1.0.11 (2021-12-01)

  • Introduced end-at property so you can set the at what time (in seconds) the video will end. The default value, 0, means video will play to the end. This way you can create short loops from youtube video backgrounds.

v1.0.10 (2021-11-14)

  • Added events on play/pause and mute/unmute actions.
  • Source element, the one with attribute data-youtube is no longer being replaced by a new element wrapping the iframe, but it becomes the wrapper instead. This way we can correctly listen to events.
  • Fixed pause/play bug caused by carelessly introducing the start-at feature.

2021-11-12

  • v1.0.9: 'start-at' property introduced - now you can set in seconds when the background video will start; bugfix

2020-03-28

  • v1.0.8: Added more options.

2020-03-27

  • v1.0.7: A bit of refactoring and bug fixes

2020-03-26

  • Refactored in vanilla JS due to Youtube API event.target property naming changes the video was no longer resizing because the target iFrame could no longer be found.

2019-12-15

  • Added more configs.

2019-12-10

  • Fixed for mobile

2019-12-08

  • Added an option to disable the plugin on mobile devices.
  • Added an option that allows the visitor to pause the video.

This awesome jQuery plugin is developed by stamat. For more Advanced Usages, please check the demo page or visit the official website.