LazyLoad is a fast, lightweight and flexible script that speeds up your web application by loading images, video or iframes as they enter the viewport. It's written in plain "vanilla" JavaScript, uses Intersection Observers, and supports responsive images. It's also SEO-friendly and it has some other notable features.

➡️ Jump to: 👨‍💻 Include the script - 🥧 Recipes - 📺 Demos - 😋 Tips & tricks - 🔌 API - 😯 Notable features

The latest, recommended version of LazyLoad is 10.20.1.

• On browsers supporting the IntersectionObserver API, it will load your images as they enter the viewport.
• On browsers not supporting it it will load all your lazy content immediately, unless you load an IntersectionObserver polyfill like this in your page (before LazyLoad). Polyfill.io is a way to do that.

Legacy browsers support is from IE 9 up.

Version 8.x still exists and works on npm, cdnjs and jsdelivr but it's now deprecated. The reason is that IntersectionObserver support is very wide now. IE 11 will soon disappear from our radars, in the meantime you can use the polyfill there. Or not.

The official w3c polyfill could be loaded conditionally on less recent versions of Safari and Internet Explorer, using Polyfill.io.

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

The file lazyload.min.js is provided as UMD (Universal Module Definition).
See bundles for more module types like AMD, IIFE and ES6 module.

It's possible to include it as an async script and make it work as soon as it's loaded. See the recipes section for more information.

If you use RequireJS to dynamically load modules in your website, you can take advantage of it.

define("vanilla-lazyLoad", ["https://cdn.jsdelivr.net/npm/[email protected]/dist/lazyload.amd.min.js"], function (LazyLoad) {
    return LazyLoad;
});

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

npm install vanilla-lazyload

Install with bower is also possible using bower install vanilla-lazyload

Download one the latest releases. The files you need are inside the dist folder.

The file lazyload.min.js is provided as UMD (Universal Module Definition).
See bundles for more module types like AMD, IIFE and ES6 module.

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

import LazyLoad from "vanilla-lazyload";

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

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

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

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

Inside dist folder you find different bundles.

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

💡 Use case: your lazy images are (normally) located in the body of a scrolling page.

HTML

<img class="lazy" alt="..." 
     data-src="../img/44721746JJ_15_a.jpg"
     width="220" height="280">

Javascript

var myLazyLoad = new LazyLoad({
    elements_selector: ".lazy"
});

DEMO - SOURCE - API

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

HTML

<div class="scrollingPanel">
    <img alt="Image description" 
         data-src="../img/44721746JJ_15_a.jpg" 
         width="220" height="280">
    <!-- More images -->
</div>

CSS

.scrollingPanel {
    overflow-y: scroll;
    -webkit-overflow-scrolling: touch;
}

Javascript

var myLazyLoad = new LazyLoad({
    container: document.getElementById('scrollingPanel')
});

DEMO - SOURCE - API

💡 Use case: when your scrolling container is not the main browser window, and you have multiple scrolling containers.

HTML

<div id="scrollingPanel1" class="scrollingPanel">
    <img alt="Image description" 
         data-src="../img/44721746JJ_15_a.jpg" 
         width="220" height="280">
    <!-- More images -->
</div>
<div id="scrollingPanel2" class="scrollingPanel">
    <img alt="Image description" 
         data-src="../img/44721746JJ_15_a.jpg" 
         width="220" height="280">
    <!-- More images -->
</div>

CSS

.scrollingPanel {
    overflow-y: scroll;
    -webkit-overflow-scrolling: touch;
}

Javascript

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

DEMO - SOURCE - API

💡 Use case: you want to lazily load responsive images using the srcset and the sizes attribute.

HTML

<img class="lazy" data-src="/your/image1.jpg"
    data-srcset="/your/image1.jpg 200w, /your/[email protected] 400w"
    data-sizes="(min-width: 20em) 35vw, 100vw">

Javascript

var myLazyLoad = new LazyLoad({
    elements_selector: ".lazy"
});

DEMO - SOURCE - API

💡 Use case: you want to lazily load responsive images using the picture tag.

HTML

<picture>
    <source media="(min-width: 1024px)" data-srcset="/your/image1a.jpg" />
    <source media="(min-width: 500px)" data-srcset="/your/image1b.jpg" />
    <img class="lazy" alt="Stivaletti" data-src="/your/image1.jpg">
</picture>

Please note that you just need to put the lazy class on the <img> tag but not in the <source> tags.

Javascript

var myLazyLoad = new LazyLoad({
    elements_selector: ".lazy"
});

DEMO - SOURCE - API

💡 Use case: you want the images to stay inside the viewport for some time before to start loading them, e.g. to skip loading some images them if the user scrolled fast after them.

HTML

<img class="lazy" alt="..." 
     data-src="../img/44721746JJ_15_a.jpg"
     width="220" height="280">

Javascript

var myLazyLoad = new LazyLoad({
    elements_selector: ".lazy",
    load_delay: 300 //adjust according to use case
});

DEMO | SOURCE | API

💡 Use case: you want to lazily load videos using the video tag.

HTML

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

Javascript

var myLazyLoad = new LazyLoad({
    elements_selector: ".lazy"
});

DEMO - SOURCE - API

💡 Use case: you want to lazily load iframes.

HTML

<iframe class="lazy" data-src="https://some.page.com" frameborder="0"></iframe>

Javascript

var myLazyLoad = new LazyLoad({
    elements_selector: ".lazy"
});

DEMO - SOURCE - API

💡 Use case: you want to use a non-blocking script (which is faster), and you don't need to have control on the exact moment when LazyLoad is created.

Include the following scripts at the end of your HTML page, right before closing the body tag.

HTML + Javascript

<script>
window.lazyLoadOptions = {
    /* your lazyload options */
};
</script>

<!-- Download the script and execute it after lazyLoadOptions is defined -->
<script async src="https://.../lazyload.min.js"></script>

If you need multiple async instances, just pass window.lazyLoadOptions an array of settings.

<script>
window.lazyLoadOptions = [{
    /* your instance 1 options */
}, {
    /* your instance 2 options */
}];
</script>

<!-- Download the script and execute it after lazyLoadOptions is defined -->
<script async src="https://.../lazyload.min.js"></script>

Please note that if you put the script at the beginning of your HTML page, LazyLoad will sometimes be executed before the browser has loaded all the DOM. In that case, you need to store the instance in a variable and use the update method on it. This will make it check the DOM again. See API.

DEMO - SOURCE - API

💡 Use case: you want to use a non-blocking script (which is faster), you don't need to have control on the exact moment when LazyLoad is created, but you need to assign the an auto-initialized instance to a variable, e.g. to use the API on it.

HTML + Javascript

<script>
// Listen to the Initialized event
window.addEventListener('LazyLoad::Initialized', function (e) {
    // Get the instance and puts it in the lazyLoadInstance variable
    lazyLoadInstance = e.detail.instance;
}, false);

// Set the lazyload options for async usage
lazyLoadOptions = {
    /* your lazyload options */
};
</script>

<!-- Download the script and execute it after lazyLoadOptions is defined -->
<script async src="https://.../lazyload.min.js"></script>

You will then have the auto-generated instance in the lazyLoadInstance variable.

DEMO - SOURCE - API

Note about Internet Explorer

LazyLoad uses CustomEvent (learn more to trigger the LazyLoad::Initialized, but this event type is not natively supported by Internet Explorer. If you want to use asynchronous loading and need to store the instance you can use the following polyfill to enable support for Internet Explorer.

(function () {
    if (typeof window.CustomEvent === "function") {
        return false;
    }

    function CustomEvent(event, params) {
        params = params || {bubbles: false, cancelable: false, detail: undefined};
        var evt = document.createEvent("CustomEvent");
        evt.initCustomEvent (event, params.bubbles, params.cancelable, params.detail);
        return evt;
    }

    CustomEvent.prototype = window.Event.prototype;
    window.CustomEvent = CustomEvent;
})();

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

HTML

The HTML to use depends on your case, see other recipes' HTML

Javascript

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

DEMO - SOURCE - API

💡 Use case: you want to lazily load iframes in your web page, maybe because you have many or just because you want to load only what your users actually want to see.

HTML

<iframe data-src="iframes/i01.html" frameborder="0"></iframe>

Javascript

var myLazyLoad = new LazyLoad({
    elements_selector: "iframe"
});

DEMO - SOURCE - API

💡 Use case: your images are set as CSS background images instead of real img, but you still want to lazily load them.

HTML

<div class="lazy" data-bg="url(../img/44721746JJ_15_a.jpg)"></div>

Javascript

var myLazyLoad = new LazyLoad({
    elements_selector: ".lazy"
});

That's it. LazyLoad copies the value of the data-bg attribute in the background-image inline style of the element, given that the element is not an img, iframe or video.

Please note that:

• you need to use url() in the value of your data-bg attribute
• you can specify multiple images as background, i.e. using url(file1.jpg), url(file2.jpg)
• using data-src for background images is deprecated, and works only for single background images when data-bg is left blank

DEMO - SOURCE - API

💡 Use case: when you have a lot of scrolling containers in the page and you want to instantiate a LazyLoad only on the ones that are in the viewport.

HTML

<div class="horzContainer">
    <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="horzContainer">
    <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 = [];
// The "lazyLazy" instance of lazyload is used (kinda improperly) 
// to check when the .horzContainer divs enter the viewport
var lazyLazy = new LazyLoad({
    elements_selector: ".horzContainer",
    // When the .horzContainer div enters the viewport...
    callback_set: function(el) {
        // ...instantiate a new LazyLoad on it
        var oneLL = new LazyLoad({
            container: el
        });
        // Optionally push it in the lazyLoadInstances 
        // array to keep track of the instances
        lazyLoadInstances.push(oneLL);
    }
});

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

DEMO - SOURCE - API

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

The demos folder contains 15 use cases of LazyLoad. You might find there what you're looking for.

You need to be sure that the images that are going to be lazy loaded occupy some vertical space (*), ideally the same space of the loaded images. Otherwise, all the images will be loaded at once.

In an elastic layout where images width change, you want to keep vertical space maintaining the images height, using a width/height ratio calculation.

.image-wrapper {
    width: 100%;
    height: 0;
    padding-bottom: 66.67%; /* You define this doing height / width * 100% */
    position: relative;
}
.image {
    width: 100%;
    /*height: auto;*/
    position: absolute;
}

More info in Sizing Fluid Image Containers with a Little CSS Padding Hack by Andy Shora.

There's also a useful SASS mixin to maintain aspect ratio on CSS tricks.

@mixin aspect-ratio($width, $height) {
  position: relative;
  &:before {
    display: block;
    content: "";
    width: 100%;
    padding-top: ($height / $width) * 100%;
  }
  > .content {
    position: absolute;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
  }
}

Images should be shown while they load, and not after, to give your users the best perceived performance. This is especially true if you use a progressive loading format like Progressive JPEG.

In order to make your images visible as soon as LazyLoad sets the src/srcset attribute to it, you can either:

Do it like that via CSS:

/* Prevents img without src to appear */
img:not([src]) {
    visibility: hidden;
}

Or instead of the above :not() selector do it using the CSS classes of class_loading and class_loaded set by LazyLoad when loading starts or is completed - see API.

We do not recommend to use a placeholder image (like a transparent pixel GIF) in your HTML.

• For best perceived preformance, leave the src and srcset attributes blank. Doing so, the image will be shown as soon as LazyLoad starts loading the image. See this video or this pen to test the difference (remember to disable the cache and to set a slower connection speed if you have a very fast one).
• If you put anything in the src (like a transparent GIF), then LazyLoad starts loading the image but it won't be shown by browsers until the new image is loaded, leading to a worse perceived performance.

It's safe not to put any value in the src nor srcset attributes, even if your HTML won't validate by a static code analyzer. The reason is that once JavaScript is executed, those values will be set by LazyLoad. For SEO, if the client is a crawler like Googlebot, it will be detected by LazyLoad which will fix the HTML.

According to what reported in #152, for Microsoft Edge to fire the IntersectionObserver for an img element, it must have a size. Since imgs are displayed inline-block as standard, MS Edge (version not specified) doesn't read them correctly.

By setting the following, edge is able to see the images and they get loaded.

img[data-src],
img[data-srcset] {
  display: block;
  min-height: 1px;
}

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 rare cases where you can't or don't want to select the elements using elements_selector and you have a reference variable to your elements set (can be a NodeSet or an array of elements), you can pass the elements set as second parameter.

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

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

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

LazyLoad doesn't hide your images from search engines, even if you don't specify any initial src for your image.

As LazyLoad doesn't rely on jQuery, you can use it in web applications using Angular, React or Vue.js without the need to include jQuery.

LazyLoad supports responsive images, both via the srcset & sizes attributes and via the picture tag.

Progressive JPEG is an image format which is very good for perceived performance because it's rendered sooner, and refined in progressive passes. LazyLoad shows your images while they load, letting progressive JPEG do its magic.

Instead of listening to the scroll and resize events, LazyLoad uses the Intersection Observer API which is a new, blazing fast method to detect if an element is inside the browser viewport. Your users will see the difference in slow and even in fast devices or computers.

This script is comparable to the notorious jQuery_lazyload, but LazyLoad is 10x faster, because LazyLoad uses only optimized, native javascript functions and methods, instead of jQuery.