Vanilla Lazyload

LazyLoad is a lightweight (2.4 kB) and flexible script that speeds up your web application by deferring the loading of your below-the-fold images, animated SVGs, videos and iframes to when they will enter the viewport. It's written in plain "vanilla" JavaScript, it leverages the IntersectionObserver API, it supports responsive images, it optimizes your website for slower connections, and can enable native lazy loading. See all features for more.

➡️ Jump to: 👨‍💻 Getting started - HTML - 👩‍💻 Getting started - Script - 🥧 Recipes - 📺 Demos - 😋 Tips & tricks - 🔌 API - 😯 All features compared

---

Love this project? 😍 Buy me a coffee!

---

👨‍💻 Getting started - HTML

In order to make your content be loaded by LazyLoad, you must use some data- attributes instead of the actual attributes. Examples below.

Lazy image:

<img alt="A lazy image" class="lazy" data-src="lazy.jpg" />

Lazy image with low quality placeholder:

<img alt="A lazy image" class="lazy" src="lazy-lowQuality.jpg" data-src="lazy.jpg" />

Lazy responsive image with srcset and sizes:

<img
  alt="A lazy image"
  class="lazy"
  data-src="lazy.jpg"
  data-srcset="lazy_400.jpg 400w, 
    lazy_800.jpg 800w"
  data-sizes="100w"
/>

To have a low quality placeholder, add the src attribute pointing to a very small version of the image. E.g. src="lazy_10.jpg".

Lazy responsive image with hi-dpi support using the picture tag:

<picture>
  <source media="(min-width: 1200px)" data-srcset="lazy_1200.jpg 1x, lazy_2400.jpg 2x" />
  <source media="(min-width: 800px)" data-srcset="lazy_800.jpg 1x, lazy_1600.jpg 2x" />
  <img alt="A lazy image" class="lazy" data-src="lazy.jpg" />
</picture>

To have a low quality placeholder, add the src attribute pointing to a very small version of the image to the img tag. E.g. src="lazy_10.jpg".

Lazy responsive image with automatic WebP format selection, using the picture tag:

<picture>
  <source
    type="image/webp"
    data-srcset="lazy_400.webp 400w, 
      lazy_800.webp 800w"
    data-sizes="100w"
  />
  <img
    alt="A lazy image"
    class="lazy"
    data-src="lazy.jpg"
    data-srcset="lazy_400.jpg 400w, 
      lazy_800.jpg 800w"
    data-sizes="100w"
  />
</picture>

To have a low quality placeholder, add the src attribute pointing to a very small version of the image to the img tag. E.g. src="lazy_10.jpg".

Lazy background image

⚠ IMPORTANT NOTE: To display content images on your pages, always use the img tag. This would benefit the SEO and the accessibility of your website. To understand if your images are content or background, ask yourself: "would my website user like to see those images when printing out the page?". If the answer is "yes", then your images are content images and you should avoid using background images to display them.

Single background image:

<div class="lazy" data-bg="lazy.jpg"></div>

Single background, with HiDPI screen support:

<div class="lazy" data-bg="lazy.jpg" data-bg-hidpi="lazy@2x.jpg"></div>

Multiple backgrounds:

<div
  class="lazy"
  data-bg-multi="url(lazy-head.jpg), 
    url(lazy-body.jpg), 
    linear-gradient(#fff, #ccc)"
>
  ...
</div>

Multiple backgrounds, HiDPI screen support:

<div
  class="lazy"
  data-bg-multi="url(lazy-head.jpg),
    url(lazy-body.jpg),
    linear-gradient(#fff, #ccc)"
  data-bg-multi-hidpi="url(lazy-head@2x.jpg),
    url(lazy-body@2x.jpg),
    linear-gradient(#fff, #ccc)"
>
  ...
</div>

Backgrounds with image-set:

<div class="lazy" data-bg-set="url('lazy@1x.jpg') 1x, url('lazy@2x.jpg') 2x">...</div>

Multiple backgrounds with image-set:

<div
  class="lazy"
  data-bg-set="
    url('lazy-head@1x.jpg') 1x, url('lazy-head@2x.jpg') 2x | 
    url('lazy-body@1x.jpg') 1x, url('lazy-body@2x.jpg') 2x
  "
>
  ...
</div>

Lazy animated SVG

<object class="lazy" type="image/svg+xml" data-src="lazy.svg"></object>

Lazy video

<video class="lazy" controls width="620" data-src="lazy.mp4" data-poster="lazy.jpg">
  <source type="video/mp4" data-src="lazy.mp4" />
  <source type="video/ogg" data-src="lazy.ogg" />
  <source type="video/avi" data-src="lazy.avi" />
</video>

Please note that the video poster can be lazily loaded too.

Lazy iframe

<iframe class="lazy" data-src="lazyFrame.html"></iframe>

---

Love this project? 😍 Buy me a coffee!

---

👩‍💻 Getting started - Script

The latest, recommended version of LazyLoad is 19.1.3. Note that if you need to support Internet Explorer 11, you need to use version 17.9.0 or below.

Quickly understand how to upgrade from a previous version reading the practical upgrade guide.

The simple, easiest way

The easiest way to use LazyLoad is to include the script from a CDN.

<script src="https://cdn.jsdelivr.net/npm/vanilla-lazyload@19.1.3/dist/lazyload.min.js"></script>

OR, if you prefer to import it as an ES module:

<script type="module">
  import LazyLoad from "https://cdn.jsdelivr.net/npm/vanilla-lazyload@19.0.3/+esm";
</script>

Then, in your javascript code:

var lazyLoadInstance = new LazyLoad({
  // Your custom settings go here
});

To be sure that DOM for your lazy content is ready when you instantiate LazyLoad, place the script tag right before the closing </body> tag.

If more DOM arrives later, e.g. via an AJAX call, you'll need to call lazyLoadInstance.update(); to make LazyLoad check the DOM again.

lazyLoadInstance.update();

Using an async script

If you prefer, it's possible to include LazyLoad's script using async script and initialize it as soon as it's loaded.

To do so, you must define the options before including the script. You can pass:

• {} an object to get a single instance of LazyLoad
• [{}, {}] an array of objects to get multiple instances of LazyLoad, each one with different options.

<script>
  // Set the options globally
  // to make LazyLoad self-initialize
  window.lazyLoadOptions = {
    // Your custom settings go here
  };
</script>

Then include the script.

<script
  async
  src="https://cdn.jsdelivr.net/npm/vanilla-lazyload@19.1.3/dist/lazyload.min.js"
></script>

Possibly place the script tag right before the closing </body> tag. If you can't do that, LazyLoad could be executed before the browser has loaded all the DOM, and you'll need to call its update() method to make it check the DOM again.

Using an async script + getting the instance reference

Same as above, but you must put the addEventListener code shown below before including the async script.

<script>
  // Set the options globally
  // to make LazyLoad self-initialize
  window.lazyLoadOptions = {
    // Your custom settings go here
  };
  // Listen to the initialization event
  // and get the instance of LazyLoad
  window.addEventListener(
    "LazyLoad::Initialized",
    function (event) {
      window.lazyLoadInstance = event.detail.instance;
    },
    false
  );
</script>

Then include the script.

<script
  async
  src="https://cdn.jsdelivr.net/npm/vanilla-lazyload@19.1.3/dist/lazyload.min.js"
></script>

Now you'll be able to call its methods, like:

lazyLoadInstance.update();

DEMO - SOURCE ← for a single LazyLoad instance

DEMO - SOURCE ← for multiple LazyLoad instances

Local install

If you prefer to install LazyLoad locally in your project, you can!

Using npm

npm install vanilla-lazyload

Using bower

bower install vanilla-lazyload

Manual download

Download one the latest releases. The files you need are inside the dist folder. If you don't know which one to pick, use lazyload.min.js, or read about bundles.

Local usage

Should you install LazyLoad locally, you can import it as ES module like the following:

import LazyLoad from "vanilla-lazyload";

It's also possible (but unadvised) to use the require commonJS syntax.

More information about bundling LazyLoad with WebPack are available on this specific repo.

Usage with React

Take a look at this example of usage of React with LazyLoad on Sandbox.

This implementation takes the same props that you would normally pass to the img tag, but it renders a lazy image. Feel free to fork and improve it!

Bundles

Inside the dist folder you will find different bundles.

| Filename