Skip to main content

Video Hero Banner Simple. Accessible. Performant.

Let's Face It...

Video banners can often be a performance and accessibility nightmare for your website's visitors. And when your clients and colleagues are demanding that you implement them, well, what is a weary, performance-minded and accessibility lovin' front-end developer to do? Enter: Video Hero Banner.

Video Hero Banner (VHB) is built with performance and accessibility in mind. Now you can have your cake and eat it, too!


VHB is easy to implement. First, just pepper in a little semantic HTML goodness to lay down your foundation:

<div id="hero-banner" data-banner-desktop="hero-banner-video-lg.mp4" data-banner-mobile="hero-banner-video-sm.mp4" data-banner-media="(min-width:778px)">

	<h1 class="hero-banner-heading">Video Hero Banner <b>Simple. Accessible. Performant.</b></h1>

	<img id="hero-banner-image" src="hero-banner-image.jpg" alt="">

	<!-- Note: The fallback image is optional, but strongly recommended in event the script fails or video not supported -->


Add the following parameters:


This is the primary id for the CSS and JavaScript and is required.


Similar to the picture elements media attribute, a valid min or max width property and viewport size are required. Parenthesis must be included in this value. For example: data-banner-media="(min-width:550px)".


A valid URL to your optimized, mobile video is required. This will load on smaller screens, specified by breakpoint value in your data-banner-media attribute. For example: data-banner-mobile="my-video-sm.mp4"


A valid URL to your optimized desktop video is required. This will load on larger screens, specified by breakpoint value in your data-banner-media attribute. For example: data-banner-desktop="my-video-sm.mp4"


A valid URL to your optimized video is required. Use this parameter if you wish to load in a single video for all viewports. For example: data-banner-all="my-video.mp4".

Note: The data-banner-mobile, data-banner-desktop and data-banner-media settings are ignored when this attribute is used.

CSS and JavaScript

Finally, just copy the CSS (Sass) and JavaScript into your own site. You may modify as needed.

Attention: Please do not link directly to any of these assets.


Not everybody likes things that move on the web. Vestibular disorders and epilepsy are but two disabilities that our work can have an adverse effect on. This is why it was important to include support for the prefers-reduced-motion media query. This will prevent the banner from playing if the user has enabled the reduced motion setting on their device. In the event that this media query is not supported, a pause button has been included in the interface. This should never be removed and may also serve to benefit short-term disabilities that may come up for your users. Win!

The pause button sets a cookie called heroBannerPaused, which will be used by the website on return visits and on other pages within the site that utilize the same script. When the video is played, this cookie is removed.

Note: Video may not load when a device is in "Low Power Mode". This is not a bug, but a feature of the device to save power, which video can drain a lot of.


There are a lot of different tools out there to optimize your video. For our demo, HandBrake was used for this task. If you would like to use this tool to optimize your own videos, then this tutorial is a great place to begin.

Tip: Make sure your banner videos are no more than 20-30 seconds long. The smaller in length, the better.

Note: A User Preset is available to download and import into HandBrake. This may serve useful for beginners.

Alternative Layouts


All issue can be found on Github.

If you discover a bug or would like to see a new feature, please open a new issue.


If you wish to contribute, fork this project, make some changes, and create a pull request.

New to GitHub? Learn the basics with the guide and learn the GitHub flow.