wistia-lazyload.js - Lazy Load Wistia Videos

wistia-lazyload.js is a lightweight and flexible vanilla JavaScript library to make lazy loading Wistia videos super easy! Wistia videos load a lot of resources in order for them to work, which can negatively impact the load time of your site. Using wistia-lazyload.js you can you can defer the loading of videos outside the viewport until just before a user scrolls to them, improving your site's performance and giving your users a better experience.

Key Features

• Easily embed and lazy load Wistia videos
• Built to prevent content shifting
• Support for Wistia embed options including popovers
• Add placeholder images (these can also be lazy loaded)
• Customisable styling: you can override the default styles with your own

Check out the live demo to see it in action!

Table of Contents

1. Download
2. Installation
   1. Module Import
   2. Local & Script Tag
   3. CDN & Script Tag
3. Getting Started
4. Placeholder Images
5. Customisation
   1. Wistia Embed Options
   2. Custom Styling
6. Browser Support
7. Non-Affiliation Disclaimer
8. Licence

1. Download

Download the wistia-lazyload.min.js script (alternatively you can download the files via npm: npm install wistia-lazyload.js --save-dev). If you wish to use a CDN you can skip to here.

2. Installation

Option 1: Module Import

Import the script file into your main JavaScript file.

import wistiaLazyload from "./wistia-lazyload.js";

Option 2: Local & Script Tag

Include the downloaded script in the head of your HTML.

<script src="wistia-lazyload.min.js" defer></script>

Option 3: CDN & Script Tag

Include the script using CDN in the head of your HTML.

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/wistia-lazyload.min.js" defer></script>

3. Getting Started

Add the following to your website and swap the video ID for your own one.

<div class="wistia-lazyload">
  <div data-video-id="vhkqhqhzyq"></div>
</div>

4. Placeholder Images

You can add a placeholder image that will appear before the Wistia video is downloaded. There are two options for this, use src to have the image download immediately or data-src to lazy load the image.

<div class="wistia-lazyload">
  <img data-src="placeholder.webp">
  <div data-video-id="vhkqhqhzyq"></div>
</div>

5. Customisation

Wistia Embed Options

If you would like to use some of the Wistia embed options you can do so by adding the options as classes to the inner div.

<div class="wistia-lazyload">
  <div data-video-id="vhkqhqhzyq" class="videoFoam=true playerColor=ff0000"></div>
</div>

Custom Styling

The included styles are designed to stop content shifting and ensure the videos are only visible once they are ready to be watched. If you would prefer to use your own styles you can do so by overriding the default styles using !important. Use the .wistia-lazyload class which is used before the video has loaded and the .wistia-lazyloaded class which is used once the video is ready to be watched. For example, the default aspect ratio is 16/9 but if you wanted to change that you could add the following to your CSS.

.wistia-lazyload, {
  aspect-ratio: 4/3 !important;
}

Inline styles can also be used override the defaults.

<div class="wistia-lazyload" style="aspect-ratio: 4/3;">
  <div data-video-id="vhkqhqhzyq"></div>
</div>

6. Browser Support

In order for the library to know when to load the videos it uses the relatively new Intersection Observer API, which has been supported by all the main browsers since 2019, and in many case earlier (compatibility table). For browsers that do not currently support this API the videos will load immediately. If you would like to lazy load Wistia videos even on older browsers you may want to include a polyfill (untested) in your project.

7. Non-Affiliation Disclaimer

This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with Wistia Inc, or any of its subsidiaries or its affiliates. The name Wistia as well as related names, marks, emblems and images are registered trademarks of their respective owners.

The official Wistia website can be found at wistia.com.

8. Licence

wistia-lazyload.js is licenced under the MIT Licence.