verlok/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!

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

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

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

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

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

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

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

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

<div class="lazy" data-bg="lazy.jpg" data-bg-hidpi="[email protected]"></div>

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

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

<div class="lazy" data-bg-set="url('[email protected]') 1x, url('[email protected]') 2x">...</div>

<div
  class="lazy"
  data-bg-set="
    url('[email protected]') 1x, url('[email protected]') 2x | 
    url('[email protected]') 1x, url('[email protected]') 2x
  "
>
  ...
</div>

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

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

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

Love this project? 😍 Buy me a coffee!

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 easiest way to use LazyLoad is to include the script from a CDN.

<script src="https://cdn.jsdelivr.net/npm/[email protected]/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/[email protected]/+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();

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/[email protected]/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.

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/[email protected]/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

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

npm install vanilla-lazyload

bower install vanilla-lazyload

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.

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.

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!

Inside the dist folder you will find different bundles.

Love this project? 😍 Buy me a coffee!

This is the section where you can find ready to copy & paste code for your convenience.

💡 Use case: when your lazily loaded images show their alt text and the empty image icon before loading.

CSS

img:not([src]):not([srcset]) {
  visibility: hidden;
}

Just that, really.

💡 Use case: when you want to prevent showing unexisting/broken images on your website.

Javascript

var myLazyLoad = new LazyLoad({
  // Other options here...
  callback_error: (img) => {
    // Use the following line only if your images have the `srcset` attribute
    img.setAttribute("srcset", "[email protected] 1x, [email protected] 2x");
    img.setAttribute("src", "[email protected]");
  }
});

NOTE: if the error was generated by a network down (navigator if temporarily offline), vanilla-lazyload will try and load the images again when the network becomes available again.

EXAMPLE - API

💡 Use case: when you want to lazily load images, but the number of images change in the scrolling area changes, maybe because they are added asynchronously.

Javascript

var myLazyLoad = new LazyLoad();
// After your content has changed...
myLazyLoad.update();

DEMO - SOURCE - API

💡 Use case: you want to use the use_native option to delegate the loading of images, iframes and videos to the browsers engine where supported, but you also want to lazily load background images.

HTML

<img class="lazy" alt="A lazy image" data-src="lazy.jpg" />
<iframe class="lazy" data-src="lazyFrame.html"></iframe>
<video class="lazy" controls data-src="lazy.mp4" data-poster="lazy.jpg">...</video>
<object class="lazy" type="image/svg+xml" data-src="lazy.svg"></object>
<div class="lazy" data-bg="lazy.jpg"></div>

Javascript

// Instance using native lazy loading
const lazyContent = new LazyLoad({
  use_native: true // <-- there you go
});

// Instance without native lazy loading
const lazyBackground = new LazyLoad({
  // DON'T PASS use_native: true HERE
});

DEMO - SOURCE - API

💡 Use case: when your scrolling container is not the main browser window, but a scrolling container.

HTML

<div class="scrollingPanel">
  <!-- Set of images -->
</div>

Javascript

var myLazyLoad = new LazyLoad({
  container: document.querySelector(".scrollingPanel")
});

DEMO - SOURCE - API

If you have multiple scrolling panels, you can use the following markup and code.

HTML

<div id="scrollingPanel1" class="scrollingPanel">
  <!-- Set of images -->
</div>
<div id="scrollingPanel2" class="scrollingPanel">
  <!-- Set of images -->
</div>

Javascript

var myLazyLoad1 = new LazyLoad({
  container: document.getElementById("scrollingPanel1")
});
var myLazyLoad2 = new LazyLoad({
  container: document.getElementById("scrollingPanel2")
});

DEMO - SOURCE - API

💡 Use case: when you want to execute arbitrary scripts or functions when given elements enter the viewport

HTML

<div class="lazy" data-lazy-function="foo">...</div>
<div class="lazy" data-lazy-function="bar">...</div>
<div class="lazy" data-lazy-function="buzz">...</div>
<div class="lazy" data-lazy-function="booya">...</div>

JS

// It's a best practice to scope the function names inside a namespace like `lazyFunctions`.
window.lazyFunctions = {
  foo: function (element) {
    element.style.color = "red";
    console.log("foo");
  },
  bar: function (element) {
    element.remove(element);
    console.log("bar");
  },
  buzz: function (element) {
    var span = document.createElement("span");
    span.innerText = " - buzz!";
    element.appendChild(span);
    console.log("buzz");
  },
  booya: function (element) {
    element.classList.add("boo");
    console.log("booya");
  }
};

function executeLazyFunction(element) {
  var lazyFunctionName = element.getAttribute("data-lazy-function");
  var lazyFunction = window.lazyFunctions[lazyFunctionName];
  if (!lazyFunction) return;
  lazyFunction(element);
}

var ll = new LazyLoad({
  unobserve_entered: true, // <- Avoid executing the function multiple times
  callback_enter: executeLazyFunction // Assigning the function defined above
});

Use unobserve_entered to avoid executing the function multiple times.

That's it. Whenever an element with the data-lazy-function attribute enters the viewport, LazyLoad calls the executeLazyScript function, which gets the function name from the data-lazy-function attribute itself and executes it.

DEMO - SOURCE - API

💡 Use case: when you have a lot of horizontally scrolling containers and you want to instantiate a LazyLoad instance on them, but only when they entered the viewport.

HTML

<div class="horizContainer">
  <img
    src=""
    alt="Row 01, col 01"
    data-src="https://placeholdit.imgix.net/~text?txtsize=19&amp;txt=row_01_col_01&amp;w=200&amp;h=200"
  />
  <img
    src=""
    alt="Row 01, col 02"
    data-src="https://placeholdit.imgix.net/~text?txtsize=19&amp;txt=row_01_col_02&amp;w=200&amp;h=200"
  />
  <!-- ... -->
</div>
<div class="horizContainer">
  <img
    src=""
    alt="Row 02, col 01"
    data-src="https://placeholdit.imgix.net/~text?txtsize=19&amp;txt=row_02_col_01&amp;w=200&amp;h=200"
  />
  <img
    src=""
    alt="Row 02, col 02"
    data-src="https://placeholdit.imgix.net/~text?txtsize=19&amp;txt=row_02_col_02&amp;w=200&amp;h=200"
  />
  <!-- ... -->
</div>

Javascript

var lazyLoadInstances = [];

var initOneLazyLoad = function (horizContainerElement) {
  // When the .horizContainer element enters the viewport,
  // instantiate a new LazyLoad on the horizContainerElement
  var oneLL = new LazyLoad({
    container: horizContainerElement
  });
  // Optionally push it in the lazyLoadInstances
  // array to keep track of the instances
  lazyLoadInstances.push(oneLL);
};

// The "lazyLazy" instance of lazyload is used to check
// when the .horizContainer divs enter the viewport
var lazyLazy = new LazyLoad({
  elements_selector: ".horizContainer",
  callback_enter: initOneLazyLoad,
  unobserve_entered: true // Stop observing .horizContainer(s) after they entered
});

That's it. Whenever a .horizContainer element enters the viewport, LazyLoad calls the initOneLazyLoad function, which creates a new instance of LazyLoad on the .horizContainer element.

DEMO - SOURCE - API

Love this project? 😍 Buy me a coffee!

Didn't find the recipe that exactly matches your case? We have demos!

The demos folder contains 30+ use cases of vanilla-lazyload. You might find there what you're looking for.

Love this project? 😍 Buy me a coffee!

It's very important to make sure that your lazy images occupy some space even before they are loaded, otherwise the img elements will be shrinked to zero-height, causing your layout to shift and making lazyload inefficient.

The best way to do that is to set both width and height attributes to img and video elements and, if you choose not to use a placeholder image, apply the display: block CSS rule to every image.

You can find more details and demos in my article aspect-ratio: A modern way to reserve space for images and async content in responsive design.

Love this project? 😍 Buy me a coffee!

The new LazyLoad() instruction you execute on your page can take two parameters:

The most common usage of LazyLoad constructor is to pass only the options object (see "options" in the next section). For example:

var aLazyLoad = new LazyLoad({
  /* options here */
});

In the unusual cases when you can't select the elements using elements_selector, you could pass the elements set as a second parameter. It can be either a NodeSet or an array of DOM elements.

var elementsToLazyLoad = getElementSetFromSomewhere();
var aLazyLoad = new LazyLoad(
  {
    /* options here */
  },
  elementsToLazyLoad
);

For every instance of LazyLoad you can pass in some options, to alter its default behaviour. Here's the list of the options.

Instance methods

You can call the following methods on any instance of LazyLoad.

Static methods

You can call the following static methods on the LazyLoad class itself (e.g. LazyLoad.load(element, settings)).

You can use the following properties on any instance of LazyLoad.

Love this project? 😍 Buy me a coffee!

A list of all vanilla-lazyload features, compared with other popular lazy loading libraries.

Weights source: bundlephobia. Find others table rows explanation below.

Both scripts are extendable, check out the API.

Both scripts don't hide images/assets from search engines. No matter what markup pattern you use. Search engines don't scroll/interact with your website. These scripts detects whether or not the user agent is capable to scroll. If not, they reveal all images instantly.

If your mobile users are on slow connections and scrolls down fast, vanilla-lazyload cancels the download of images that are still loading but already exited the viewport.

If your mobile users are on flaky connections and go offline and back online, vanilla-lazyload retries downloading the images that errored.

If your users are on a browser supporting native lazyloading and you want to use it, just set the use_native option to true.

Both scripts work by default with the data-src attribute and the lazy class in your DOM, but on LazyLoad you can change it, e.g. using data-origin to migrate from other lazy loading script.

Both scripts can lazyload images and responsive images by all kinds, e.g. <img src="..." srcset="..." sizes="..."> and <picture><source media="..." srcset="" ...><img ...></picture>.

lazysizes is it can derive the value of the sizes attribute from your CSS by using Javascript. vanilla-lazyload doesn't have this feature because of performance optimization reasons (the sizes attribute is useful to eagerly load responsive images when it's expressed in the markup, not when it's set by javascript).

Both scripts can lazyload the iframe tag.

Only vanilla-lazyload can load animated SVGs via the object tag.

Only vanilla-lazyload can lazyload the video tag, even with multiple sources.

Only vanilla-lazyload can lazyload background images. And also multiple background images. And supporting HiDPI such as Retina and Super Retina display.

Check out the lazy functions section and learn how to execute code only when given elements enter the viewport.

Using the restoreAll() method, you can make LazyLoad restore all DOM manipulated from LazyLoad to how it was when the page was loaded the first time.

Love this project? 😍 Buy me a coffee!

This script is tested in every browser before every release using BrowserStack live, thanks to the BrowserStack Open Source initiative.