Use Youtube/Vimeo/HTML5 Videos As A Fullscreen Background - youtube-background.js
File Size: | 98.9 KB |
---|---|
Views Total: | 22727 |
Last Update: | |
Publish Date: | |
Official Website: | Go to website |
License: | MIT |
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.7 (2024-03-26)
- Setting injected scripts for YouTube and Vimeo to be async so to minimize initial main thread blocking
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.