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-video data-banner-desktop="hero-banner-video-lg.mp4" data-banner-mobile="hero-banner-video-sm.mp4" data-banner-media="(min-width:778px)">

	<!-- Note: If you only have one video to load, be sure to use data-banner-all. The data-banner-media attribute will not be required if this attribute is used. Also, in all cases, be sure to optimize your videos! -->

	<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 image is required if you wish to include a custom image when video is paused on page load. The graphic also actts as a fallback in JavaScript is not present or broken.  -->


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. A win for all!

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.


The following parameters are avilable for use:


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


This is the flag that the script uses to load the video. It takes no value and is required if you want the video banner to load. This is handy for when you only want video banner to appear on certain pages, but not others that may use the same wrapper id.


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-lg.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.


In the event you load a hero banner with audio, captions must be present for the hearing impaired. The parameter requires three, comma-delimited values. These are the path to the caption file (usually a VTT), the ISO two letter language code and a label to idendify the caption. For example: data-banner-caption="my-video-en.vtt, en, English".

Multiple captions, for different languages, are also supported. For example: data-banner-caption="my-video-caption-en.vtt, en, English, my-video-caption-es.vtt, es, Espanol".

Note: Loading captions will be the only way to unmute a video with audio. (This is by design.) Video with captions will also enable default video controls and remeove the single pause button.

Plug: For low-cost, fast and accurate caption production, please give Rev a try.


In the event you require audio descriptions, a parameter with three comma-delimited values, is required. These are the path to the audio description file (usually a VTT), the ISO two letter language code and a label to idendify the description. For example: data-banner-description="my-video-description-en.vtt, en, English".

Multiple audio descriptions, for different languages, are also supported. For example: data-banner-description="my-video-audio-description-en.vtt, en, English, my-video-audio-description-es.vtt, es, Espanol".

Note: Audio descriptions are not currently supported in browsers, but you can test them out using a browser plugin.

Alternative Layouts

There are many different and unique ways you may wish to design your banners. The only limit is your imagination.

In the Wild

If you are using on your own site, then please let me know!


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.