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.

Love this project? 😍 Buy me a coffee!

🥧 Recipes

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

Hide alt text and empty image

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

Image errors handling

💡 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", "fallback_image@1x.jpg 1x, fallback_image@2x.jpg 2x");
    img.setAttribute("src", "fallback_image@1x.jpg");
  }
});

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

Dynamic content

💡 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

Mixed native and JS-based lazy loading

💡 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

Scrolling panel(s)

💡 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

Lazy functions

💡 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

Lazy initialization of multiple LazyLoad instances

💡 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!

📺 Demos

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!

😋 Tips & tricks

Minimize CLS by occupy space beforehand

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!

🔌 API

Constructor arguments

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
);

Options

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

Methods

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

Properties

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

Love this project? 😍 Buy me a coffee!

😯 All features, compared

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

vanilla-lazyload VS lazysizes

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

Is extendable

Both scripts are extendable, check out the API.

Is SEO friendly

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.

Optimizes performance by cancelling downloads of images that already exited the viewport

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.

Retries loading after network connection went off and on

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

Supports conditional usage of native lazyloading

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

Works with your DOM, your own classes and data-attributes

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.

Can lazyload responsive images

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

...and automatically calculate the value of the sizes attribute

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

Can lazyload iframes

Both scripts can lazyload the iframe tag.

Can lazyload animated SVGs

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

Can lazyload videos

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

Can lazyload background images

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

Can lazily execute code, when given elements enter the viewport

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

Can restore DOM to its original state

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!

Tested on real browsers

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

CHANGELOG

Version 19

19.1.3

• File CHANGELOG.md is now included in the package and installed along with it
• Updated Babel, Rollup and Playwright to the latest versions

19.1.2

• Modernized code and smaller file bundles, everything is now shipped as in the ES2015 format.

19.1.1

• Removed code to support image-set on legacy versions of Chromium browsers
• Added coverage with 2 more demos for images with single src and a placeholder image

19.1.0

• Added end to end tests to expand test coverage to more use cases and cross browser

19.0.5

• Removed .eslintrc.json, LICENSE, CHANGELOG.md, CODE_OF_CONDUCT.md, README.md, package.json from the package files, as they didn't have any impact on code quality.

19.0.4

• Removed Babel plugin to polyfill Object.assign(), as suggested in #611.

19.0.3

• Files .eslintrc.json, LICENSE, CHANGELOG.md, CODE_OF_CONDUCT.md, README.md, package.json are now included in the package

19.0.1

• Restored compatibility for bundlers that used this module, see #609

19.0.0

• Rollup setup enhancement
  • Refactored the Rollup setup to improve performance and maintainability.
  • Switched to ES6 module format for better compatibility and readability.
  • Enabled tree shaking and module preservation to optimize the build output.
• Added ESM demo to showcase the functionality of the esm module.
• Updated various dependencies to their latest versions for better compatibility and security
• Removed AMD module from the /dist folder, as it's been unused since version 11
• Removed AMD-related demos

Version 18

18.0.0

• Dropped support for Internet Explorer 11
• Modernized code
• Smaller file

Version 17

17.9.0

• Allowing to pass empty string ("") as value for class options (class_loading, class_applied, class_loaded, class_error, class_entered, class_exited) so that no DOM mutation will happen if not necessary. This is a potential performance improvement. Suggested in #605.

17.8.8

• Fixed dependency issues detected by npm audit

17.8.5

• Improved callbacks check by introducing type check (must be function)

17.8.4

• Updated link to demos in the documentation.

17.8.3

• Fixed callback_error in background images demos, like suggested in #573. Thanks to @Soul244.

17.8.2

• Fixed a bug which occurred if the network connection went off and on again after a LazyLoad instance was destroyed

17.8.1

• Updated Typescript typings

17.8.0

• Added the ability to lazyload background images with CSS image-set() via data-bg-set.

17.7.0

• Added the new option restore_on_error to restore original attributes on error.

17.6.1

• Removed nasty "debugger" from code (sorry about that rookie mistake!)

17.6.0

• Added ability to lazily load the <object> tag, as requested in #177. Useful to lazily load animated SVGs.

17.5.1

• Updated Typescript typings

17.5.0

• Added the ability to restore DOM to its original state through the restoreAll() method.
• Destroy demo became restore and destroy demo

17.4.0

• Adding native lazy loading for videos, as discussed in #527. Thanks to @saschaeggi.
• Updated the native_lazyload_conditional.html demo with the new best practice for cross browser native lazy loading.

17.3.2

• Fixes double trigger of callback_load after a watched image was loaded using the static load() method (#526). Thanks to @nick-vincent.

17.3.1

• Removed caniuse-lite from dependencies. Fixes #505. Thanks to @ar53n.

17.3.0

• Added class_entered and class_exited options to apply a class when an element entered and/or exited the viewport

17.2.0

• Rolling back the "data attribute cleanup" feature that was released on 16.1.0 and was causing issues like #484 when more than one instance of LazyLoad were working on the same elements of the page - the script is also 500 bytes lighter now

17.1.3

• Added missing types (#480), thanks to @ar53n (#482)

17.1.2

• Fixed TypeScript typings (#475), thanks to @ar53n (#477)

17.1.1

• Fixing npm audit vulnerabilities

17.1.0

• Unobserve all elements on loadAll() call. It's better for performance, and it solves #469.
• Added some hidden images in the load_all.html demo

17.0.1

• Bug fix: callback_exit() was not being called on non-image elements (#468).

17.0.0

• The elements_selector option now defaults to .lazy (was img)
• The cancel_on_exit option now defaults to true (was false)

See UPGRADE.md to understand if you are impacted by any breaking change and how to upgrade from previous versions.

Love this project? 😍 Buy me a coffee!

Version 16

16.1.0

Improved speed, cleaning DOM, better working destroy, and also fixed 2 bugs.

• Cleaning up data attributes from the DOM when finished using them (mainly when elements have finished loading)
• Improved destroy method, which now also removes lazyload's additions to the DOM elements
• Video elements are now only listening to the loadeddata event, no longer to load
• Removed constants containing strings. I thought it would produced shorter minified code, but discovered that terser expands them to strings.
• Bugfix: when lazily loading videos, the error _poster_ is undefined was thrown
• Bugfix: when selecting native lazy loading, the loading class was added without knowing whether or not the loading had started

16.0.0

Functional changes:

• Removed call to deprecated callback_reveal
• Removed deprecated instance load() method in favor of the static LazyLoad.load() method
• Replaced auto_unobserve with unobserve_completed, still defaulting to true
• Introduced a new unobserve_entered option (useful to execute lazy functions once)
• Created a demo called lazy_functions.html to show how to execute functions as elements enter the viewport
• Wrote a new recipe to facilitate the lazy execution of scripts/functions
• Renamed instance method resetElementStatus() to the static LazyLoad.resetStatus()
• Removed the load_delay option since there's no more use for it
• Removed the load_delay related demos

See UPGRADE.md to understand if you are impacted by any breaking change and how to upgrade from previous versions.

Internal changes:

• Simplified management of the cancel_on_exit with less increase/decrease of the toLoadCount property
• Refactored counters functions in a new lazyload.counters file

Love this project? 😍 Buy me a coffee!

Version 15

15.2.0

OPTIMIZE FOR SLOW CONNECTIONS WITH cancel_on_exit

Want to optimize speed for users who scroll down fast on a slow connection? Just set cancel_on_exit: true and LazyLoad will cancel the download of images exiting the viewport while still loading, eventually restoring the original attributes.

• Introduced the new cancel_on_exit option.
• Introduced the callback_cancel option, just in case you want to perform any additional action whenever a download gets canceled by cancel_on_exit.
• Created a new demo named cancel_on_exit.html so you can try the new cancel_on_exit option live.
• Set cancel_on_exit to true in the following demos, so you can test how it behaves...
  • image_ph_inline.html, with an inline SVG placeholder
  • image_ph_external.html, with an external SVG placeholder
  • delay_test.html, in conjuction with the delay_load option
  • fade_in.html, with a beautiful fade-in effect.

The cancel_on_exit option applies only to images so to the img (and picture) tags. It doesn't work for background images, iframes nor videos.

The cancel_on_exit option will probably default to true starting from the next major version, so give it a try! And please report your feedback in the comments of #438.

API

• Added the resetElementStatus() method for when you need to tell LazyLoad to consider an image (or other DOM element) again. This is particularly useful if you change the data-src attribute after the previous data-src was loaded). See the API section in the README file for more information.

FIX

• The callback_exit callback was called several times (for every images out of the viewport) at instance creation or upon update() calls. Now the callback is properly called only when any element exits the viewport.

INTERNALS

• Improved script performance by reducing the number of event listeners used for loading elements.
• Changed the values that the (internally used) data-ll-status attribute can take. Removed the status "observed" (it was useless) and introduced status "delayed".

15.1.1

Fixed a bug when loading lazy background images on HiDPI screens, data-bg-hidpi was mandatory, not it fallbacks to data-bg. #430

15.1.0

Lazy background images just gained support for hiDPI ("retina") screens! Place your standard resolution images in the data-bg attribute and your hiDPI images in data-bg-hidpi. Same for data-bg-multi and data-bg-multi-hidpi.

15.0.0

Lazy background images gained loaded/error classes and callbacks! 🎉

Breaking changes impacting lazy background images! ⚠ See UPGRADE.md to understand if you are impacted and how to upgrade from previous versions.

• Lazy loading of one background image using the data-bg attribute, now manages the load and error events, so they are applied the classes defined in the class_loading/class_loaded/class_error, and the callbacks defined in callback_loading/callback_loaded/callback_error.
• Lazy loading of multiple background images is still possible via the data-bg-multi attribute. In this case, the load and error events are not managed. The class_applied and callback_applied can be used to understand when the multiple background was applied to the element.
• Updated background images demos:
  • background-images.html -> single background images
  • background-images-multi.html -> multiple background images
• Added UPGRADE.md, a guide on how to upgrade from previous versions (from version 12 up)

Love this project? 😍 Buy me a coffee!

Version 14

14.0.1

Fixed error TS1036: Statements are not allowed in ambient contexts. Closes #427

14.0.0

🎉 Major refactoring and performance improvement! 🔍 File size stays tiny: only 2.07 KB gZipped

Settings

• callback_loading is called when an element started loading
• callback_reveal is now ⚠ DEPRECATED, use callback_loading instead (it's the same thing, it was just renamed). callback_reveal will be removed and will stop working in version 15.

Instance methods

• update() method now also unobserves deleted elements, instead of just looking for and observing new elements
• destroy() destroys better than it did before, delete-ing properties instead of setting their values to null
• load() method (as an instance method) is now ⚠ DEPRECATED, use the static method instead. If you were using aLazyLoadInstance.load(element) you should change it to LazyLoad.load(element, settings).

Static methods

• load() was added as a static method. Note that if you need to use custom settings, you need to pass them in the settings parameter.

Instance properties

• Added toLoadCount. It's the counter of the elements that haven't been lazyloaded yet.

DOM

• Removed the data-was-processed attribute, that was added to mark lazy DOM elements as "already managed". If you were manually handling that attribute to obtain some goal, this is a potentially breaking change. You should now refer to the data-ll-status instead.
• Added the data-ll-status attribute, which is now used to mark the status of a lazy DOM element. The values it can take are: observing (not loaded yet), loading (loading started), loaded (load completed), error (an error has occured), native (similar to observing, but managed by native lazy loading).

Love this project? 😍 Buy me a coffee!

Version 13

13.0.1

• Fixed a JS error that could happen to IE11 users after going offline and back online
• Minor refactoring for better readibility and lighter code (and files)!

13.0.0

• Added the minified version of dist/lazyload.esm.js as dist/lazyload.esm.min.js, so now you can effortlessly use it with an ES module import statement when using type="module"
• Reduced files weight even more! dist/lazyload.iife.min.js now weights only 2.03 KB GZipped
• Removed the callback_set callback that was deprecated since version 11 in favour of callback_reveal
• Removed sourcemaps (they were probably used only by the authors, but if anyone was actually needing them, we can bring them back)
• Hidden the _extends function inside LazyLoad's scope (it was global before)
• Updated build tooling: removed Gulp, now using Rollup & Babel only

Version 12

12.5.1

Restored IE 11 compatibility, which was broken since 12.2.0. See #414. Thanks to @ninosaurus for reporting.

12.5.0

The once-private _loadingCount property is now public and renamed to loadingCount. This property contains the number of images that are currently downloading from the network, limitedly to the ones managed by an instance of LazyLoad. This is particularly useful to understand whether or not is safe to destroy an instance of LazyLoad. See implementation in the destroy demo.

Thanks to @wzhscript and @eugene-stativka.

12.4.0

Video posters can now be loaded lazily, as requested in #365

12.3.0

Callbacks now pass more arguments!

callback_enter, callback_exit now pass:

1. the DOM element that entered / exited the viewport
2. the IntersectionObserverEntry that triggered the enter/exit event
3. the LazyLoad instance

callback_load, callback_error, callback_reveal now pass

1. the DOM element that entered / exited the viewport
2. the LazyLoad instance

callback_finish now passes:

1. the LazyLoad instance

The README file has been updated accordingly.

12.2.0

Released new feature "retry when back online". Now if your users lose the internet connection causing errors on images loading, this script tries and loads those images again when the connection is restored.

12.1.1

Solved a bug with Internet Explorer 11 and the W3C polyfill, as reported in #383.

12.1.0

• Updated npm dev dependencies
• Added the new image_ph_inline.html, with an inline SVG placeholder
• Added the new image_ph_external.html, with an external SVG placeholder

12.0.3

Updated the IntersectionObserver polyfill to version 0.7.0

12.0.2

Improved detection of browser support of IntersectionObserver, as suggested in #362. Thanks to @kaldonir

12.0.1

Updated CHANGELOG.md and README.md to mention the change of the option name callback_load which is called callback_loaded in versions 11.0.0 and above.

12.0.0

• Reorganized code
• Improved native lazy loading demos
• Aligned console messages throughout all demos.

12.0.0-beta.0

• Added the use_native option which enables native lazy loading (where supported) with the loading="lazy" attribute. See #331
• Added two demos:
  • native_lazyload_conditional.html which you can use to test the use_native option
  • native_lazyload.html which always uses native lazy loading (without JS) just to test how it works beyond the LazyLoad script
• Refactored the constructor and the update method

Version 11

11.0.6

Restored the callback_set callback as deprecated, in order to make the upgrade from v.10 easier.

11.0.5

Fixed the module property of this package.json, which was pointing to a non-existing dist file.

11.0.4

Fixed the main property of this package.json, which was pointing to a non-existing dist file.

11.0.3

Rollback of the patch applied in 11.0.2 since it gave strange results in some cases. See #293. Thanks to @davejamesmiller for the analysis and the report.

11.0.2

Applied a patch to resolve #293 a Chromium bug already fixed in Chrome 72. Thanks to @dverbovyi for the analysis and the report.

11.0.1

Squashed a nasty bug that occurred on IE 11 and Safari when the IntersectionObserver polyfill wasn't loaded before LazyLoad.

11.0.0

• Changed bundle file name of ES Module from lazyload.es2015.js to lazyload.esm.js
• Removed the to_webp option (see issue #288)
• Ceased support and development of LazyLoad v.8 (see issue #306) version. If you were using it, please update your code to use callback_reveal instead.
• Private methods like _setObserver, _onIntersection etc. are now hidden from the outside.
• Added the auto_unobserve boolean option, see API.
• Bugfix: loadAll() didn't unobserve elements.
• Updated to Jest 24, Babel 7, etc.
• Fixed dev dependencies vulnerabilities
• Updated callbacks. See below:

Callbacks updated:

• Changed callback_enter. This callback is now called whenever an element enters the viewport, even when load_delay is set. In previous versions, this callback was delayed until an element started loading if a load_delay was set. Note that this is a possible breaking change, which you can fix using callback_reveal instead.
• Renamed callback_loaded is the new name of callback_load.
• Added callback_exit. This callback is called whenever an element exits the viewport, even if a load_delay is set.
• Added callback_reveal. This callback is called just after an element starts loading.
• Deprecated callback_set. This callback still works*, but will be removed in the next major

* it didn't work from versions 11.0.0 to 11.0.5, it still works from 11.0.6.

Version 10

10.20.1

Fixed a bug for which LazyLoad didn't copy the data-sizes attribute value to sizes in source tags inside picture. See #307.

10.20.0

Improved WebP detection to work correctly on Firefox too, see #298.

Thanks to @ipernet for contributing.

10.19.1

• Fixed build for those using React + SSR, see #287
• TypeScript definitions clearified, see #283
• Gulp updated to v.4.0.0 to make it work with node 10

Thanks to @AlexCSR and @muturgan for contributing.

10.19.0

• Added the ability to know when all images have been downloaded through the callback_finish callback.
• Added the file demos/print.html to demo how to print lazy images.

10.18.0

Added the ability to have multiple background images, through the new data_bg option.

10.17.0

Added the ability to set different thresholds for the scrolling area, through the new thresholds option.

10.16.2

BUGFIX: Class loaded was not applied to a loaded video (issue #239).

10.16.1

BUGFIX: Autoplaying video not loaded correctly after entering the viewport (issue #240). Thanks to @maeligg.

10.16.0

Added new option load_delay to skip loading when fast scrolling occurs, as requested in issues #235 and #166. Pass in a number of milliseconds, and each image will be loaded after it stayed inside that viewport for that time.

10.15.0

• Refactorized code & improved script performance
• BUGFIX: Fixed webpack import (issue #230) TypeError: default is not a constructor

10.14.0

Now supporting WebP through dynamic extension rename if the user browser is compatible.

10.13.0

• Shortened the RegEx for crawlers detection (shaved a few bytes)
• Released LazyLoad in new module types! Enjoy the new flavours :)

10.12.0

SEO! Expanded SEO-friendliness to more crawlers, Bingbot included.

10.11.1

BUGFIX: Fixed issue #225. Due to mistyped BOT detection, in version 10.11.0 all images were loaded as soon as LazyLoad was created.

10.11.0

SEO! Version 10.x is now as SEO-friendly as version 8.x.

10.10.0

Added a public load method to lazyload any element.

10.9.0

Added the ability to lazily set the sizes attribute via a data-sizes attribute. See the README file for more information.

10.8.0

Added a public loadAll method to loading all the images at once, as asked in #193.

10.7.0

• Added support for the <video> HTML tag and descending <source> tags. Now you can lazily load your videos too!
• Created the video.html demo.

10.6.0

• Added a demo with a popup layer and images injected after popup open, to help with #196.
• Updated the background_images demo with a custom management of the loading class and the loaded event callback.

10.5.2

Added a security check on lazy elements' parents.

10.5.1

Just a refactoring over previous version.

10.5.0

Added node support by merging pull request #188, "node-support" by @klarstrup.

With these changes in place, simply importing vanilla-lazyload without using it won't crash Node by itself. This is important for isomorphic/universal/server rendered setups where the same code runs on both the server and the browser.

10.4.2

Fixed a bug for which sometimes images wouldn't reveal on Chrome 65 (see issue #165).

10.4.1

Updated dist folder.

10.4.0

Added the callback_enter callback, which is called whenevery any element managed by LazyLoad enters the viewport, as requested in #159. Thanks to @alvarotrigo.

10.3.6

Fixed tests to match dataset revert made in 10.3 and 8.2 (oopsy).

10.3.5

Fixed a bug that could occur on older versions of IE when trying to access an image's parent node.

10.3.4

Fixed a CustomEvent bug which occurred on IE when using async object initialization.

10.3.3

Fixed supportsClassList test to work even when the document object isn't yet there. Thanks to @Spone and his pull request #145.

10.3.1

Introduced a workaround for an issue of Microsoft Edge documented here

10.3.0

Restored support to IE9 and IE10, as requested in #118 and #132.

10.2.0

To solve cases when you can't select the elements to load using a string, added the ability to pass a NodeList object...

• as a second parameter in the constructor, after the regular option object, e.g. var ll = new Lazyload({}, myNodeList)
• as a single parameter to the update() method, e.g. ll.update(myNodeList)

10.1.0

To solve cases when you can't select the elements to load using a string, added the ability to pass a NodeList object to the elements_selector option, as suggested by @SassNinja in #130.

10.0.1

Solved a problem with cdnjs.com: version 10.0.0 was pointing to 9.0.0.

10.0.0

• Change in default options:
  • default for data_src is now src (was original)
  • default for data_srcset is now srcset (was original-set)

Version 9

9.0.1

• Restored tests using Jest
• Squashed a bug which didn't make images inside picture load correctly

9.0.0

LazyLoad is now faster thanks to the Intersection Observer API.

IMPORTANT! Browser support changed. Find more information in the README file.

Version 8

8.17.0

• Added the ability to know when all images have been downloaded through the callback_finish callback.
• Added the file demos/print.html to demo how to print lazy images.

8.16.0

Added the ability to have multiple background images, through the new data_bg option.

8.15.2

BUGFIX: Class loaded was not applied to a loaded video (issue #239).

8.15.1

BUGFIX: Autoplaying video not loaded correctly after entering the viewport (issue #240). Thanks to @maeligg.

8.15.0

• Refactorized code & improved script performance
• BUGFIX: Fixed webpack import (issue #230) TypeError: default is not a constructor

8.14.0

Now supporting WebP through dynamic extension rename if the user browser is compatible.

8.13.0

• Shortened the RegEx for crawlers detection (shaved a few bytes)
• Released LazyLoad in new module types! Enjoy the new flavours :)

8.12.0

SEO! Expanded SEO-friendliness to more crawlers, Bingbot included.

8.11.0

Added a public load method to lazyload any element.

8.10.0

Added the ability to lazily set the sizes attribute via a data-sizes attribute. See the README file for more information.

8.9.0

Added a public loadAll method to load all the images, as asked in #193.

8.8.0

Added support for the video tag. Closes #209. Created the video.html demo.

8.7.1

Added a security check on lazy elements' parents.

8.7.0

Added node support by merging pull request #188, "node-support" by @klarstrup.

With these changes in place, simply importing vanilla-lazyload without using it won't crash Node by itself. This is important for isomorphic/universal/server rendered setups where the same code runs on both the server and the browser.

8.6.0

Added the callback_enter callback, which is called whenevery any element managed by LazyLoad enters the viewport, as requested in #159. Thanks to @alvarotrigo.

8.5.2

Fixed a bug that could occur on older versions of IE when trying to access an image's parent node.

8.5.1

Fixed a CustomEvent bug which occured on IE when using async object initialization.

8.5.0

• Change in default options, in order to be aligned with version 10
  • default for data_src is now src (was original)
  • default for data_srcset is now srcset (was original-set)

8.2.1

Fixed supportsClassList test to work even when the document object isn't yet there. Thanks to @Spone and his #145.

8.2.0

Restored support to IE9 and IE10, as requested in #118 and #132.

8.1.0

Updated from grunt to gulp (run with gulp scripts).

8.0.3

Added quotes in background image URLs, as suggested in #114 (thanks to @vseva).

8.0.2

Fixed a bug that affected performance.

8.0.1

Fixed reference to old names in demo files.

8.0.0

• The main file to include is now dist/lazyload.min.js as you would expect, and no longer dist/lazyload.transpiled.min.js.
• The non-transpiled version is now named lazyload.es2015.js

Version 7

7.2.0

• Now using element.dataset to read data attributes
• New readme! New website!

Bug fixes:

• Fixed #87

IMPORTANT! Browser support changed. Find more information in the README file.

7.1.0

• Refactored code now using more modules
• Saving ~0.5 kb of transpiled code going back from ES2015 class to function's prototype

7.0.0

Source code converted to ES2015 modules, bundled with rollup.js and transpiled with babel.

Version 6

6.3.x

Added the class initial to all images (or iframes) inside the viewport at the moment of script initialization

6.2.x

• Added the ability to load LazyLoad using an async script

6.1.x

SEO improvements for lazily loaded images

6.0.x

• Source code migrated to ES6 / ES2015
• Serving both minified ES6 version and minified transpiled-to-ES5 version

Version 5

• Exposed private functions for test coverage
• Test coverage

Version 4

• Lighter constructor
• Performance improvements
• Bugfix: null on background images
• Removed code for legacy browsers - now supporting IE10+

Version 3

• Added support to the picture tag
• Removed the "show image only when fully loaded" mode
  • Dumped the show_while_loading and placeholder options

Version 2

• Added support to lazily load iframes and background images
• Added error management callback and error class option
• Performance improvements

Version 1

• Added support to the srcset attribute for images
• Added typescript typings + updated dist folder files
• Performance improvements
• Stable release of LazyLoad

Want more detail? Take a look at the release history on GitHub!