mohbadar / lazyload Goto Github PK

LazyLoad is a fast, lightweight and flexible script that speeds up your web application by loading your content images, videos and iframes only as they enter the viewport. It's written in plain "vanilla" JavaScript, it leverages the IntersectionObserver API, it works with responsive images and it supports native lazy loading. See notable features for more.

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

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

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

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

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

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

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

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

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

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

Single background

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

Multiple backgrounds

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

Notes:

• you need to use url() in the value of your data-bg attribute, also for single background
• you shouldn't use background images to load content images, they're bad for SEO and for accessibility
• on background images, callback_loaded won't be called and the class_loaded class won't be added

<video class="lazy" controls width="620"
    data-src="lazy.mp4" 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>

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

The latest, recommended version of LazyLoad is 12.0.0.

On browser NOT supporting IntersectionObserver such as Internet explorer and older versions of Safari you can choose whether or not to add a javascript polyfill for it.

If you don't use a polyfill, LazyLoad will load all the images as soon as it's downloaded and executed. The number of impacted users would be relatively small, so this is a completely acceptable choice.

If you prefer to load a polyfill, the regular LazyLoad behaviour is granted.

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

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

Or, with the IntersectionObserver polyfill:

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

Then, in your javascript code:

var lazyLoadInstance = new LazyLoad({
    elements_selector: ".lazy"
    // ... more custom settings?
});

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.

if (lazyLoadInstance) {
    lazyLoadInstance.update();
}

You can use RequireJS to dynamically and asynchronously load modules in your website.

You can also find the original W3C'S IntersectionObserver Polyfill packed in AMD so you can require it conditionally, along with LazyLoad.

Include RequireJS:

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

Then require the AMD version of LazyLoad, like this:

var lazyLoadAmdUrl = "https://cdn.jsdelivr.net/npm/[email protected]/dist/lazyload.amd.min.js";
var polyfillAmdUrl = "https://cdn.jsdelivr.net/npm/[email protected]/intersection-observer-amd.js";

/// Dynamically define the dependencies
var dependencies = [
    "IntersectionObserver" in window
        ? null // <- Doesn't require the polyfill
        : polyfillAmdUrl,
    lazyLoadAmdUrl
];

// Initialize LazyLoad inside the callback
require(dependencies, function(_, LazyLoad) {
    var lazyLoadInstance = new LazyLoad({
        elements_selector: ".lazy"
        // ... more custom settings?
    });
}

DEMO - SOURCE

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 to make LazyLoad self-initialize	
    window.lazyLoadOptions = {	
        elements_selector: ".lazy",	
        // ... more custom settings?	
    };
</script>	

Then include the script.

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

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

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

<script>	
    // Set the options to make LazyLoad self-initialize	
    window.lazyLoadOptions = {	
        elements_selector: ".lazy",	
        // ... more custom settings?	
    };
    // 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:

if (lazyLoadInstance) {
    lazyLoadInstance.update();
}

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

<script>
// CustomEvent micro-polyfill 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;
})();
</script>

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

npm install vanilla-lazyload

bower install vanilla-lazyload

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

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

import LazyLoad from "vanilla-lazyload";

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

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

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

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

Inside the dist folder you will find different bundles.

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

💡 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: when your scrolling container is not the main browser window, but a scrolling container.

HTML

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

Javascript

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

DEMO - SOURCE - API

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

HTML

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

Javascript

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

DEMO - SOURCE - API

💡 Use case: if a your scrolls fast over your images, you might wait a short time before the images start loading. This is how.

HTML

<img class="lazy" alt="A lazy image" 
     data-src="lazy.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: 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_enter: 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_enter 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 20+ use cases of LazyLoad. You might find there what you're looking for.

You need to be sure that the containers of the images that are going to be lazy loaded occupy some vertical space. This because if the images have an initial height of 0, all of them will probably be inside the viewport before time, so they will be loaded all 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 performance, 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 the 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.

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.

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.

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

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

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.