rvp

responsive-video-poster

Responsive poster image for videos to improve performance and allow full control of video placeholders.

Showing:

Popularity

Downloads/wk

3

GitHub Stars

28

Maintenance

Last Commit

4mos ago

Contributors

2

Package

Dependencies

0

Size (min+gzip)

1.7KB

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

Responsive Video Poster

Responsive poster image for videos to improve performance and allow full control of video placeholders.

Video elements only allow one image as the poster, which is not optimal for performance. This JavaScript plugin uses a standard image tag as the poster. This means standard responsive image techniques can be used to load only the most appropriate image. This also gives full styling control of video placeholders. Performance optimizations are also included for loading of both native and embedded videos.

View demo


Installation

$ npm install responsive-video-poster --save-dev

Usage

Import JS

The script is an ES6(ES2015) module but the compiled version is included in the build as "src/scripts/responsive-video-poster-umd.js". You can also copy "src/scripts/responsive-video-poster.js" into your own site if your build process can accommodate ES6 modules.

import ResponsiveVideoPoster from 'responsive-video-poster.js';

const responsiveVideoPosterDefault = ResponsiveVideoPoster({ 
  selector: '#responsive-video-poster--default' 
});

Options

PropertyDefaultTypeDescription
selector'.responsive-video-poster'StringContainer element selector.
overlaySelector'.video-overlay'StringOverlay element selector.
posterSelector'.poster'StringPoster element selector.
videoSelector'.video'StringVideo element selector.
animClass'is-anim'StringCSS class to transition the video overlay between states.
inactiveClass'is-inactive'StringCSS class to hide the video overlay.
playDelay0Integer(ms) or 'transitionDelay playing the video by set time or wait for the overlay transition to finish.
hideControlsOnLoadfalseBooleanHide video controls while transitioning overlay.
preConnections[]ArrayDomains to pre-connect for loading an embedded video.

API

PropertyTypeDescription
instance.playVideo()MethodPlays the video.
instance['elements']ObjectReturns the elements used by this

Import SASS

@import "node_modules/responsive-video-poster/src/styles/responsive-video-poster.scss";

Markup

<div class="responsive-video-poster responsive-video-poster--16by9">
                
  <button class="video-overlay" aria-label="Play video">
    <div class="poster-btn"><svg class="poster-btn-icon"> ... </svg></div>

    <img srcset="images/720/image.jpg 720w, images/1080/image.jpg 1080w" src="images/1080/image.jpg" class="poster">
  </button>

  <video src="videos/video.mp4" preload="metadata" class="video" controls></video>

</div>

Bootstrap 4 Example

<div class="responsive-video-poster embed-responsive embed-responsive-16by9">             
  ...
</div>

Bootstrap 5 Example

<div class="responsive-video-poster ratio ratio-16x9">
  ...
</div>

Video loading optimizations

Responsive image techniques(srcset, sizes, source, etc) are used to load the most appropriate image. Native lazy loading is used on the responsive poster image to reduce initial page load. The plugin should also work normally with lazy load plugins.

The video element includes preload="metadata" so the video is not loaded until the user interacts with it. This will reduce the initial page load but may create lag in playback for some users. This can be removed if not needed.

The embedded video includes srcdoc="" so the video and third-party scripts are not loaded until the user interacts with it. The 'preConnections' option can be used to pass domains to start pre-connect connections for loading an embedded video. this happens when the user hovers/taps on the video using the pointerover event. For example Youtube could use ['https://www.youtube.com', 'https://www.google.com'].


Events

A 'playVideo' event is started once a user clicks the video overlay. The event is ended once the overlay has become inactive and the video starts playing.

document.querySelector('#responsive-video-poster--default').addEventListener('playVideo', (event) => { 
  console.log(`Action: ${event.detail.action}`);
});

You can also attach this to the document.

document.addEventListener('playVideo', (event) => { 
  console.log(`Target: ${event.target.matches('#responsive-video-poster--default')}`, `Action: ${event.detail.action}`);
});

Compatibility

Supports all modern browsers (Firefox, Chrome, Safari and Edge) released as of April 2020.


Demo site

Clone or download from Github.

$ npm install
$ gulp serve

Credits

Lazy loading of an embedded video by Arthur Corenzan. Lazy load third-party resources with facades. Covverr videos of Lago di braies and Lofoten rocks. Youtube video of Tustan Karpaty mountains.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100