LazyLoad is a lightweight, flexible script that speeds up your website by deferring the loading of your below-the-fold images, backgrounds, videos, iframes and scripts to when they will enter the viewport. Written in plain "vanilla" JavaScript, it leverages IntersectionObserver, supports responsive images and enables native lazy loading.

Last update: Jan 2, 2023

Overview

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, 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="[email protected]"></div>

Multiple backgrounds:

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

ℹ Please note that you must use url() to wrap the URLs in your data-bg-multi attributes.

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([email protected]),
    url([email protected]),
    linear-gradient(#fff, #ccc)"
>
  ...
</div>

ℹ Please note that you must use url() to wrap the URLs in your data-bg-multi-hidpi attributes.

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

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/[email protected]/dist/lazyload.min.js"></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/[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.

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/[email protected]/dist/lazyload.min.js"
></script>

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

lazyLoadInstance.update();

Note about Internet Explorer: because this technique uses a CustomEvent to trigger the LazyLoad::Initialized event, you might want to add this polyfill to make it work on Internet Explorer.

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	Module Type	Advantages
`lazyload.min.js`	UMD (Universal Module Definition)	Works pretty much everywhere, even in common-js contexts
`lazyload.iife.min.js`	IIFE (Immediately Invoked Function Expression)	Works as in-page `<script src="...">`, ~0.5kb smaller than UMD version
`lazyload.amd.min.js`	AMD (Asynchronous Module Definition)	Works with RequireJS module loader, ~0.5kb smaller than UMD version
`lazyload.esm.js`	ES Module	Exports `LazyLoad` so you can import it in your project both using `<script type="module" src="...">` and a bundler like WebPack or Rollup

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", "[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

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

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

Type	Title	Code	Demo
Content	Simple lazy loaded images, not using any placeholder	Code	Live
Content	Lazy images that use an inline SVG as a placeholder	Code	Live
Content	Lazy images that use an external SVG file as a placeholder	Code	Live
Content	Lazy responsive images with `srcset`	Code	Live
Content	Lazy responsive images with the `<picture>` tag and the `media` attribute (art direction)	Code	Live
Content	Lazy responsive images with `srcset` and `sizes` (using `data-sizes`)	Code	Live
Content	Lazy responsive images with `srcset` and `sizes` (using plain `sizes`)	Code	Live
Content	Lazy video with multiple `<source>` tags, different preload options, NO autoplay	Code	Live
Content	Lazy video with multiple `<source>` tags, different preload options, WITH autoplay	Code	Live
Content	Lazy loading background images	Code	Live
Content	Lazy loading multiple background images	Code	Live
Content	Lazy WebP images with the `<picture>` tag and the `type` attribute for WebP	Code	Live
Loading	Asynchronous loading LazyLoad with requireJS	Code	Live
Loading	Asynchronous loading LazyLoad + InterserctionObserver with requireJS	Code	Live
Loading	Asynchronous loading LazyLoad with `<script async>`	Code	Live
Loading	Asynchronous loading multiple LazyLoad instances with `<script async>`	Code	Live
Technique	Fade in images as they load	Code	Live
Technique	Lazily create lazyload instances	Code	Live
Technique	Lazily create Swiper instances and lazily load Swiper images	Code	Live
Technique	Lazily execute functions as specific elements enter the viewport	Code	Live
Technique	How to manage the print of a page with lazy images	Code	Live
Technique	A popup layer containing lazy images in a scrolling container	Code	Live
Settings	Multiple scrolling containers	Code	Live
Settings	Single scrolling container	Code	Live
Methods	How to `restore()` DOM to its original state, and/or `destroy()` LazyLoad	Code	Live
Methods	Adding dynamic content, then `update()` LazyLoad	Code	Live
Methods	Adding dynamic content, then `update()` LazyLoad passing a NodeSet of elements	Code	Live
Methods	Load punctual images using the `load()` method	Code	Live
Methods	Load all images at once using `loadAll()`	Code	Live
Test	Test for multiple thresholds	Code	Live
Test	Test behaviour with hidden images	Code	Live
Test	Test performance, lazy loading of hundreds of images	Code	Live
Native	Test the native lazy loading of images WITHOUT any line of javascript, not even this script	Code	Live
Native	Test the native lazy loading of images conditionally using the `use_native` option (see API)	Code	Live

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:

Parameter	What to pass	Required	Default value	Type
Options	The option object for this instance of LazyLoad	No	`{}`	Plain Object
Nodeset	A NodeSet of elements to execute LazyLoad on	No	`null`	NodeSet

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.

Name	Meaning	Default value	Example value
`container`	The scrolling container of the elements in the `elements_selector` option.	`document`	`document.querySelector('.scrollPanel')`
`elements_selector`	The CSS selector of the elements to load lazily, which will be selected as descendants of the `container` object.	`".lazy"`	`".lazyload"`
`threshold`	A number of pixels representing the outer distance off the scrolling area from which to start loading the elements.	`300`	`0`
`thresholds`	Similar to `threshold`, but accepting multiple values and both `px` and `%` units. It maps directly to the `rootMargin` property of IntersectionObserver (read more), so it must be a string with a syntax similar to the CSS `margin` property. You can use it when you need to have different thresholds for the scrolling area. It overrides `threshold` when passed.	`null`	`"500px 10%"`
`data_src`	The name of the data attribute containing the element URL to load, excluding the `"data-"` part. E.g. if your data attribute is named `"data-src"`, just pass `"src"`	`"src"`	`"lazy-src"`
`data_srcset`	The name of the data attribute containing the image URL set to load, in either `img` and `source` tags, excluding the `"data-"` part. E.g. if your data attribute is named `"data-srcset"`, just pass `"srcset"`	`"srcset"`	`"lazy-srcset"`
`data_sizes`	The name of the data attribute containing the sizes attribute to use, excluding the `"data-"` part. E.g. if your data attribute is named `"data-sizes"`, just pass `"sizes"`	`"sizes"`	`"lazy-sizes"`
`data_bg`	The name of the data attribute containing the URL of `background-image` to load lazily, excluding the `"data-"` part. E.g. if your data attribute is named `"data-bg"`, just pass `"bg"`. The attribute value must be a valid value for `background-image`, including the `url()` part of the CSS instruction.	`"bg"`	`"lazy-bg"`
`data_bg_hidpi`	The name of the data attribute containing the URL of `background-image` to load lazily on HiDPI screens, excluding the `"data-"` part. E.g. if your data attribute is named `"data-bg-hidpi"`, just pass `"bg-hidpi"`. The attribute value must be a valid value for `background-image`, including the `url()` part of the CSS instruction.	`"bg-hidpi"`	`"lazy-bg-hidpi"`
`data_bg_multi`	The name of the data attribute containing the value of multiple `background-image` to load lazily, excluding the `"data-"` part. E.g. if your data attribute is named `"data-bg-multi"`, just pass `"bg-multi"`. The attribute value must be a valid value for `background-image`, including the `url()` part of the CSS instruction.	`"bg-multi"`	`"lazy-bg-multi"`
`data_bg_multi_hidpi`	The name of the data attribute containing the value of multiple `background-image` to load lazily on HiDPI screens, excluding the `"data-"` part. E.g. if your data attribute is named `"data-bg-multi-hidpi"`, just pass `"bg-multi-hidpi"`. The attribute value must be a valid value for `background-image`, including the `url()` part of the CSS instruction.	`"bg-multi-hidpi"`	`"lazy-bg-multi-hidpi"`
`data_poster`	The name of the data attribute containing the value of `poster` to load lazily, excluding the `"data-"` part. E.g. if your data attribute is named `"data-poster"`, just pass `"poster"`.	`"poster"`	`"lazy-poster"`
`class_applied`	The class applied to the multiple background elements after the multiple background was applied	`"applied"`	`"lazy-applied"`
`class_loading`	The class applied to the elements while the loading is in progress.	`"loading"`	`"lazy-loading"`
`class_loaded`	The class applied to the elements when the loading is complete.	`"loaded"`	`"lazy-loaded"`
`class_error`	The class applied to the elements when the element causes an error.	`"error"`	`"lazy-error"`
`class_entered`	The class applied to the elements after they entered the viewport.	`"entered"`	`"lazy-entered"`
`class_exited`	The class applied to the elements after they exited the viewport. This class is removed if an element enters the viewport again. The `unobserve_entered` option can affect the appliance of this class, e.g. when loading images that complete loading before exiting.	`"exited"`	`"lazy-exited"`
`cancel_on_exit`	A boolean that defines whether or not to cancel the download of the images that exit the viewport while they are still loading, eventually restoring the original attributes. It applies only to images so to the `img` (and `picture`) tags, so it doesn't apply to background images, `iframe`s nor `video`s.	`true`	`false`
`unobserve_entered`	A boolean that defines whether or not to automatically unobserve elements once they entered the viewport	`false`	`true`
`unobserve_completed`	A boolean that defines whether or not to automatically unobserve elements once they've loaded or throwed an error	`true`	`false`
`callback_enter`	A callback function which is called whenever an element enters the viewport. Arguments: DOM element, intersection observer entry, lazyload instance.	`null`	`(el)=>{console.log("Entered", el)}`
`callback_exit`	A callback function which is called whenever an element exits the viewport. Arguments: DOM element, intersection observer entry, lazyload instance.	`null`	`(el)=>{console.log("Exited", el)}`
`callback_loading`	A callback function which is called whenever an element starts loading. Arguments: DOM element, lazyload instance.	`null`	`(el)=>{console.log("Loading", el)}`
`callback_cancel`	A callback function which is called whenever an element loading is canceled while loading, as for `cancel_on_exit: true`.	`null`	`(el)=>{console.log("Cancelled", el)}`
`callback_loaded`	A callback function which is called whenever an element finishes loading. Note that, in version older than 11.0.0, this option went under the name `callback_load`. Arguments: DOM element, lazyload instance.	`null`	`(el)=>{console.log("Loaded", el)}`
`callback_error`	A callback function which is called whenever an element triggers an error. Arguments: DOM element, lazyload instance.	`null`	`(el)=>{console.log("Error", el)}`
`callback_applied`	A callback function which is called whenever a multiple background element starts loading. Arguments: DOM element, lazyload instance.	`null`	`(el)=>{console.log("Applied", el)}`
`callback_finish`	A callback function which is called when there are no more elements to load and all elements have been downloaded. Arguments: lazyload instance.	`null`	`()=>{console.log("Finish")}`
`use_native`	This boolean sets whether or not to use native lazy loading to do hybrid lazy loading. On browsers that support it, LazyLoad will set the `loading="lazy"` attribute on images, iframes and videos, and delegate their loading to the browser.	`false`	`true`

Methods

Instance methods

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

Method name	Effect	Use case
`update()`	Make LazyLoad to re-check the DOM for `elements_selector` elements inside its `container`.	Update LazyLoad after you added or removed DOM elements to the page.
`loadAll()`	Loads all the lazy elements right away and stop observing them, no matter if they are inside or outside the viewport, no matter if they are hidden or visible.	To load all the remaining elements in advance
`restoreAll()`	Restores DOM to its original state. Note that it doesn't destroy LazyLoad, so you probably want to use it along with `destroy()`.	Reset the DOM before a soft page navigation (SPA) occures, e.g. using TurboLinks.
`destroy()`	Destroys the instance, unsetting instance variables and removing listeners.	Free up some memory. Especially useful for Single Page Applications.

Static methods

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

Method name	Effect	Use case
`load(element, settings)`	Immediately loads the lazy `element`. You can pass your custom options in the `settings` parameter. Note that the `elements_selector` option has no effect, since you are passing the element as a parameter. Also note that this method has effect only once on a specific `element`.	To load an `element` at mouseover or at any other event different than "entering the viewport"
`resetStatus(element)`	Resets the internal status of the given `element`.	To tell LazyLoad to consider this `element` again, for example: if you changed the `data-src` attribute after the previous `data-src` was loaded, call this method, then call `update()` on the LazyLoad instance.

Properties

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

Property name	Value
`loadingCount`	The number of elements that are currently downloading from the network (limitedly to the ones managed by the instance of LazyLoad). This is particularly useful to understand whether or not is safe to destroy this instance of LazyLoad.
`toLoadCount`	The number of elements that haven't been lazyloaded yet (limitedly to the ones managed by the 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

It	vanilla-lazyload	lazysizes
Is lightweight	✔ (2.8 kB)	✔ (3.4 kB)
Is extendable	✔ (API)	✔ (plugins)
Is SEO friendly	✔	✔
Optimizes performance by cancelling downloads of images that already exited the viewport	✔
Retries loading after network connection went off and on again	✔
Supports conditional usage of native lazyloading	✔
Works with your DOM, your own classes and data-attributes	✔
Can lazyload responsive images	✔	✔
...and automatically calculate the value of the `sizes` attribute		✔
Can lazyload iframes	✔	✔
Can lazyload videos	✔
Can lazyload background images	✔
Can lazily execute code, when given elements enter the viewport	✔
Can restore DOM to its original state	✔

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

Legacy browsers support is from IE 9 up. This script is tested in every browser before every release using BrowserStack live, thanks to the BrowserStack Open Source initiative.

Comments

Abort/cancel loading triggered lazy images from the loading queue

I'm working on a thumbnail gallery: when you hover the mouse over a thumbnail, the related images are triggered to load for autoplay by the lazyinstance.

The problem is if the gallery A have like 12 images, and all or some of them are triggered to load, but if the user doesn't wait this and scrolls lower viewing gallery B, the images from the previous gallery A are still loading and in the loading queue. So before the images from the gallery B could load he need to wait the previously triggered images to load, even if they are not in view anymore.

Because visually nothing happens (beside a loading progress display), he moves on to gallery C, and now he need to wait gallery A and B images until the images in gallery C could start to load. The longer he tries, the more he would have to wait to actually see something.

So is there a way to abort and likely reset lazy images which are currently loading or pending but not in view anymore?
TYPE: Enhancement

opened by wzol 45
Issue with loading images on Chrome browser v 75.0.3770.80 (Official Build) (64-bit)

With lazy loading some images were loading some were not on Chrome browser Version 75.0.3770.80 (Official Build) (64-bit).

The code was -

<img class="card-img-top lazy" data-src="/Path to image">

And in script -

new LazyLoad();

I have upgraded the plugin from 11.0.3 to 12.0.0, but it did not help.

Currently I have disabled Lazy loading on our site. Can any one tell me what could be the issue?

opened by sougatabose07 34
Implement take records in intersectionObserver

Re-raise of #389

Hello,

When using React and adding some elements, if they're visible on screen it can flicker from a placeholder existing "src" to the new "data-src". Using takeRecords in update() it's possible to swap the "src" before a render so the flicker is greatly reduced.

This PR implements that.

I have updated the changes to work against master and I'm currently doing some tests on the code base I use this one, and will update once that's all working.

opened by driskell 30
Make sure Google can see lazy-loaded content

I tried to run a test for my website as suggested in this link: https://developers.google.com/search/docs/guides/lazy-loading by using a puppeteer script but the test results are: "Lazy images loaded correctly: Failed".

I then ran the test for the 2 demos provided in the docs, concerning the responsive images lazyload (srcset & with picture tag) https://www.andreaverlicchi.eu/lazyload/demos/with_srcset_lazy_sizes.html and the result was once again "Lazy images loaded correctly: Failed".

However, running the same test for the normal img demo (no srcset, no picture) the result was "passed".

Any idea what is wrong?
TYPE: Question

opened by DimLeon 29
MS Edge supported?
Using the latest version (10.3.0) I can't get lazyload to work in MS Edge 15 (latest version). Is it supported and/or are there any special steps to make it work?

var loadImages = new LazyLoad({ elements_selector: "[data-src]" });

and

<div class="m-split__image" data-src="src/static/img/work/kocianka-6.jpg"></div>

URL: http://www.via-electra.eu/2017/

Thanks!
opened by chrisjansky 29
to_webp use cases?
Hi, the to_webp flag is not so usefull since the <picture> tag is made also for that:

<picture> <source type="image/webp" srcset="flower.webp"> <source type="image/jpeg" srcset="flower.jpg"> <img src="fallback.jpg"> </picture>

It will try to load the .webp if supported, if not it will try with .jpg. If the picture tag isn't supported at all old browsers will show the <img> with the default src...

I can't figure out when using it.. maybe it can be removed to optimise the code?
TYPE: Enhancement
opened by equinusocio 28
class_loaded and callback_load for background images

Hi Andrea, I believe I am missing something here.

I am using following initialization set on v8.7.1: elements_selector: '.is-lazy', class_loaded: 'is-lazy-loaded'

Class equal to the class_loaded property is not being added to the element with data-src being set. style and data-was-processed attributes are created and set properly, as in your demo. callback_load function doesn't fire as well, if set.

I'd like to use an additional class in order to be able to control the appearance entirely on the CSS side.

Class is being added for conventional images, also using srcset.

Thank you!
TYPE: Enhancement

opened by pooledge 27
Multiple Background Images for a Single Element

Is there a way to support the lazy loading of multiple background images for a single element. EG: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Backgrounds_and_Borders/Using_multiple_backgrounds

Not critical but wondering if it is possible or too compicated
TYPE: Enhancement

opened by vigoren 23

How to lazy load images in swiper that are not yet in viewport?

Is your support request related to a problem? Please describe. I am using swiper and only the image that's currently the viewport lazy loads, the other ones only load after swiping. I'm suspecting that this is intentional, but it creates a bad UX if each image only loads when it is swiped into the viewport (= delay). I also tried to use scrollingPanel solution (by adding a div around swiper and/or within swiper). Doesn't work either.

To Reproduce Steps to reproduce the behavior:

<!-- Swiper -->
<div class="row text-center swiper" style="max-height: 100%;">
   <div class="swiper-container">
      <div class="swiper-wrapper d-flex my-auto">
         <div class="swiper-slide">
            <img class="lazy image_1 img-fluid swiper-900px"
            src="https://via.placeholder.com/1000x560?text=persona1_backup"
            data-srcset="https://via.placeholder.com/1000x560?text=persona1 600w,
                         https://via.placeholder.com/1000x560?text=persona1_large 1000w"
            >
         </div>
         <div class="swiper-slide">
            <img class="lazy image_1 img-fluid swiper-900px"
            src="https://via.placeholder.com/1000x560?text=persona2_backup"
            data-srcset="https://via.placeholder.com/1000x560?text=persona2 600w,
                         https://via.placeholder.com/1000x560?text=persona2_large 1000w"
            >
         </div>
      </div>
      <div class="swiper-pagination"></div> <!-- Add Pagination -->
      <div class="swiper-button-prev"></div> <!-- Add Arrows -->
      <div class="swiper-button-next"></div> <!-- Add Arrows -->
   </div>
</div>
<!-- Swiper end -->

Expected behavior Once the first image in swiper is in viewport, all images in that swiper should load instantly (that the user can swipe without loading delay for each image)

LazyLoad version Please report which version of LazyLoad you're using. 17.5.0

Desktop (please complete the following information): Chrome, Firefox

Screenshots

Additional context

TYPE: Question STATUS: Awaiting feedback

opened by gitbrutus 22

LazyLoad and printing
i used the conditional loading, so in firefox/chrome it uses 10.x and in safari 8.x

lazyloading of the images works in all browsers. when scrolling down the images are being loaded.

when i print the page, only the already loaded images will be printed. i tried to use

wLazyLoad = new LazyLoad({ elements_selector: '.lazy', }); window.onbeforeprint = function () { wLazyLoad.loadAll(); };

but without luck. it should load alle the images, right?

safari it will only display the already loaded images.

chrome i only see my placeholders no images. in the console and in my server logs i see the loading of the images.

firefox will load the remaining images and then prints them (checked also in the console)

TYPE: Enhancement
opened by markusweb 21
Uncaught TypeError: Assignment to constant variable (Chrome)

Can`t build for production mode with 10.17 version (dev version is well), got error: Uncaught TypeError: Assignment to constant variable. Using Laravel mix with Webpack (Laravel mix using "webpack": "^3.11.0")
TYPE: Question

opened by Somethingideally 21
Advisable to use the decoding async attribute?

First, thanks for this great script.

Is it advisable to use the decoding async attribute on image tags along with vanilla lazyload?

I searched for this topic as far as I could and found no information. I even checked other JavaScript lazyload libraries, and no issues referenced the term "decoding"

More about the optimization standard may be read here:

https://mediajams.dev/post/asynchronously-load-and-decode-images https://fantinel.dev/web-images-modern-formats/

WordPress 6.1 has added the decoding="async" attribute to all images, so it'll become more prevalent.

Thanks.
TYPE: Question

opened by bridgeport 1
Lazy loading not working with Siema image carousel
Is your support request related to a problem? Please describe. A clear and concise description of what the problem is.

To Reproduce Steps to reproduce the behavior:

Use "Siema Image Carousel script" https://github.com/pawelgrzybek/siema

12 images, 6 visible at once, Loop

scroll

Behavior Lazy loading works when images go the the right, lazy loading doesn't work after few images (images not showing) when images go to the left.

LazyLoad version

Version 17.8.3

Desktop (please complete the following information):

OS: [Windows

Browser [Chrome, Brave]

Version Brave 1.43.93

TYPE: Question
opened by Bammede 0
Use the minified esm bundle for the target of the pkg module path

This allows the imported module to be already minified, and if the environment doesn't need any additional transpiling, be used without any processing/bundling. e.g. directly via unpkg

opened by mbehzad 0
Many requests get cancelled, why?
Is your support request related to a problem? Please describe. When I scroll down a page VERY slowly and observe how the images are loaded lazy, I still see a lot of cancelled requests, why? Once in a while I also observed that resources get requested and cancelled in a loop, even though I'm not touching my computer.

Expected behavior I am the opinion that when I scroll very slowly, no single cancelled request should occur.

LazyLoad version 17.8.2

Desktop (please complete the following information):

OS: macOS Mojave 10.14.6

Browser Chrome 101.0.4951.54

Screenshots
TYPE: Question STATUS: Awaiting feedback
opened by baszero 11
cancel_on_exit not working
Describe the bug I see in the network tab, that after the component is unmounted (a new page is loaded) the images that have not finished loading from the previous page are still loading. This makes the new page slow to load as the previous page images are still loading... The lazy loading (and everything else) works properly.

To Reproduce My Image component:

import LazyLoad from "vanilla-lazyload"; if (!document.lazyLoadInstance) { document.lazyLoadInstance = new LazyLoad({ elements_selector: ".lazyload", cancel_on_exit: true }); } function ImageComp(props) { useEffect(() => { document.lazyLoadInstance.update(); }, []) return( <img className="lazyload" data-src={props.src} .... /> ) }

Expected behavior I would expect the images to stop downloading as the propert cancel_on_exit is set to true.

LazyLoad version Please report which version of LazyLoad you're using.

Version: 17.8.1

Desktop (please complete the following information):

OS: Mac OS 12

Browser: Firefox

TYPE: Question STATUS: Awaiting feedback
opened by jellohouse 3

Releases(17.8.3)

17.8.3(Apr 25, 2022)
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

Source code(tar.gz)
Source code(zip)
17.7.0(Apr 10, 2022)
17.7.0

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

Source code(tar.gz)
Source code(zip)
17.6.1(Feb 20, 2022)
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.

Source code(tar.gz)
Source code(zip)
17.5.1(Sep 23, 2021)
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

Source code(tar.gz)
Source code(zip)
17.4.0(Jun 6, 2021)
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.

Source code(tar.gz)
Source code(zip)
17.3.2(Nov 24, 2020)
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

Source code(tar.gz)
Source code(zip)
17.2.0(Nov 23, 2020)

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
Source code(tar.gz)
Source code(zip)
17.1.3(Jul 1, 2020)
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

Fixed 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

Source code(tar.gz)
Source code(zip)
17.0.1(Jun 24, 2020)
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.
Source code(tar.gz)
Source code(zip)
16.1.0(May 21, 2020)
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

Source code(tar.gz)
Source code(zip)
16.0.0(May 14, 2020)
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!
Source code(tar.gz)
Source code(zip)
15.2.0(May 7, 2020)
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".

Love this project? 😍 Buy me a coffee!
Source code(tar.gz)
Source code(zip)
15.1.1(Mar 31, 2020)

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.

Love this project? 😍 Buy me a coffee!
Source code(tar.gz)
Source code(zip)
15.0.0(Mar 31, 2020)
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!
Source code(tar.gz)
Source code(zip)
14.0.1(Mar 24, 2020)
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!
Source code(tar.gz)
Source code(zip)
13.0.1(Feb 29, 2020)
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

Source code(tar.gz)
Source code(zip)
12.5.1(Feb 24, 2020)

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.
Source code(tar.gz)
Source code(zip)
12.4.0(Nov 20, 2019)

12.4.0

Video posters can now be loaded lazily, as requested in #365
Source code(tar.gz)
Source code(zip)
12.3.0(Oct 30, 2019)
12.3.0

Callbacks now pass more arguments.

callback_enter, callback_exit now pass:

the DOM element that entered / exited the viewport

the IntersectionObserverEntry that triggered the enter/exit event

the LazyLoad instance

callback_load, callback_error, callback_reveal now pass:

the DOM element that entered / exited the viewport

the LazyLoad instance

callback_finish now passes:

the LazyLoad instance

The README file has been updated accordingly.
Source code(tar.gz)
Source code(zip)
12.2.0(Oct 21, 2019)

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.
Source code(tar.gz)
Source code(zip)
12.1.1(Oct 6, 2019)
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

Source code(tar.gz)
Source code(zip)
12.0.3(Apr 11, 2019)
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

Source code(tar.gz)
Source code(zip)
11.0.6(Feb 22, 2019)
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)

Callbacks renewal :: POSSIBLE BREAKING CHANGE

Callback callback_enter has changed its meaning! It is now called whenever an element enters the viewport, even if load_delay is set

Callback callback_exit (new) is called whenever an element exits the viewport, even if load_delay is set

Callback callback_reveal (new) is called when an element is about to be revealed, and its attribute values were copied from the data- attributes to the actual ones.

Callback callback_set was removed. You can use callback_reveal instead.

Private methods like _setObserver, _onIntersection etc. are now hidden and protected.

Added the auto_unobserve boolean option.

Bugfix: loadAll() didn't unobserve elements.

Updated to Jest 24, Babel 7, etc.

Fixed dev dependencies vulnerabilities

Source code(tar.gz)
Source code(zip)
10.20.0(Feb 7, 2019)
10.20.0

Improved WebP detection to work correctly on Firefox too as in #298.

Thanks to @ipernet
Source code(tar.gz)
Source code(zip)
10.19.1(Oct 2, 2018)
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.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.
Source code(tar.gz)
Source code(zip)
8.17.0(Oct 6, 2018)
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.

Source code(tar.gz)
Source code(zip)
8.16.0(Oct 2, 2018)

8.16.0

Added the ability to have multiple background images, through the new data_bg option.
Source code(tar.gz)
Source code(zip)
10.18.0(Sep 28, 2018)

10.18.0

Added the ability to have multiple background images, through the new data_bg option.
Source code(tar.gz)
Source code(zip)
10.17.0(Sep 8, 2018)

10.17.0

Added a new thresholds option that you can use when you need to have different thresholds for the scrolling area, so a single threshold option is not enough for your needs. Learn more in the API section of the README file.
Source code(tar.gz)
Source code(zip)
8.15.2(Aug 8, 2018)
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

Source code(tar.gz)
Source code(zip)

Related tags

Overview

👨‍💻 Getting started - HTML

Lazy image:

Lazy image with low quality placeholder:

Lazy responsive image with srcset and sizes:

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

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

Lazy background image

Lazy video

Lazy iframe

👩‍💻 Getting started - Script

The simple, easiest way

Using an async script

Using an async script + getting the instance reference

Local install

Using npm

Using bower

Manual download

Local usage

Usage with React

Bundles

🥧 Recipes

Hide alt text and empty image

Image errors handling

Dynamic content

Mixed native and JS-based lazy loading

Scrolling panel(s)

Lazy functions

Lazy initialization of multiple LazyLoad instances

📺 Demos

😋 Tips & tricks

Minimize CLS by occupy space beforehand

🔌 API

Constructor arguments

Options

Methods

Properties

😯 All features, compared

vanilla-lazyload VS lazysizes

Is extendable

Is SEO friendly

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

Retries loading after network connection went off and on

Supports conditional usage of native lazyloading

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

Can lazyload responsive images

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

Can lazyload iframes

Can lazyload videos

Can lazyload background images

Can lazily execute code, when given elements enter the viewport

Can restore DOM to its original state

Tested on real browsers

Comments

Releases(17.8.3)

17.8.3(Apr 25, 2022)

17.8.3

17.8.2

17.8.1

17.8.0

17.7.0(Apr 10, 2022)

17.7.0

17.6.1(Feb 20, 2022)

17.6.1

17.6.0

17.5.1(Sep 23, 2021)

17.5.1

17.5.0

17.4.0(Jun 6, 2021)

17.4.0

17.3.2(Nov 24, 2020)

17.3.2

17.3.1

17.3.0

17.2.0(Nov 23, 2020)

17.2.0

17.1.3(Jul 1, 2020)

17.1.3

17.1.2

Lazy responsive image with `srcset` and `sizes`:

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

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

Using an `async` script

Using an `async` script + getting the instance reference

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