JavaScripting

The definitive source of the best
JavaScript libraries, frameworks, and plugins.


  • ×

    🔥 Highly performant, light ~0.9kb and configurable lazy loader in pure JS with no dependencies for responsive images, iframes and more
    Filed under  â€º 

    • 🔾75%Overall
    • 7,379
    • 18.7 days
    • 🕩452
    • 👥17

    Lozad.js npm version Build Status npm

    Highly performant, light and configurable lazy loader in pure JS with no dependencies for images, iframes and more, using IntersectionObserver API

    lozad.js lazy loading javascript library

    Lozad.js:

    • lazy loads elements performantly using pure JavaScript,
    • is a light-weight library, just minified & gzipped,
    • has NO DEPENDENCIES :)
    • allows lazy loading of dynamically added elements as well,
    • supports <img>, <picture>, iframes, videos, audios, responsive images, background images and multiple background images etc.
    • even supports LQIP (Low Quality Image Placeholder)
    • is completely free and open source.
    • it will reload when the valid attributes change.

    It is written with an aim to lazy load images, iframes, ads, videos or any other element using the recently added Intersection Observer API and MutationObserver with tremendous performance benefits.

    Brands using Lozad.js:

    Tesla          Binance          Domino's          BNP Paribas          Mi          Amway          TATA          Verizon Atlassian BNP Paribas JLM Couture          New Balance          BBC

    and many more...

    Table of Contents

    Yet another Lazy Loading JavaScript library, why?

    Existing lazy loading libraries hook up to the scroll event or use a periodic timer and call getBoundingClientRect() on elements that need to be lazy loaded. This approach, however, is painfully slow as each call to getBoundingClientRect() forces the browser to re-layout the entire page and will introduce considerable jank to your website.

    Making this more efficient and performant is what IntersectionObserver is designed for, and it’s landed in Chrome 51. IntersectionObservers let you know when an observed element enters or exits the browser’s viewport.

    Install

    # You can install lozad with npm
    $ npm install --save lozad
    
    # Alternatively you can use Yarn
    $ yarn add lozad
    
    # Another option is to use Bower
    $ bower install lozad
    

    Then with a module bundler like rollup or webpack, use as you would anything else:

    // using ES6 modules
    import lozad from 'lozad'
    
    // using CommonJS modules
    var lozad = require('lozad')
    

    Or load via CDN and include in the head tag of your page.

    <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/lozad/dist/lozad.min.js"></script>
    

    When loading from CDN, you can find the library on window.lozad.


    Usage

    In HTML, add an identifier to the element (default selector identified is lozad class):

    <img class="lozad" data-src="image.png">
    

    All you need to do now is just instantiate Lozad as follows:

    const observer = lozad(); // lazy loads elements with default selector as '.lozad'
    observer.observe();
    

    or with a DOM Element reference:

    const el = document.querySelector('img');
    const observer = lozad(el); // passing a `NodeList` (e.g. `document.querySelectorAll()`) is also valid
    observer.observe();
    

    or with custom options:

    const observer = lozad('.lozad', {
        rootMargin: '10px 0px', // syntax similar to that of CSS Margin
        threshold: 0.1, // ratio of element convergence
        enableAutoReload: true // it will reload the new image when validating attributes changes
    });
    observer.observe();
    

    Reference:

    or if you want to give custom function definition to load element:

    lozad('.lozad', {
        load: function(el) {
            console.log('loading element');
    
            // Custom implementation to load an element
            // e.g. el.src = el.getAttribute('data-src');
        }
    });
    

    If you would like to extend the loaded state of elements, you can add the loaded option:

    Note: The "data-loaded"="true" attribute is used by lozad to determine if an element has been previously loaded.

    lozad('.lozad', {
        loaded: function(el) {
            // Custom implementation on a loaded element
            el.classList.add('loaded');
        }
    });
    

    If you want to lazy load dynamically added elements:

    const observer = lozad();
    observer.observe();
    
    // ... code to dynamically add elements
    observer.observe(); // observes newly added elements as well
    

    for use with responsive images

    <!-- responsive image example -->
    <img class="lozad" data-src="image.png" data-srcset="image.png 1000w, image-2x.png 2000w">
    

    for use with background images

    <!-- background image example -->
    <div class="lozad" data-background-image="image.png">
    </div>
    

    for use with multiple background images

    <!-- multiple background image example -->
    <div class="lozad" data-background-image="path/to/first/image,path/to/second/image,path/to/third/image">
    </div>
    

    for use with responsive background images (image-set)

    <!-- responsive background image-set example -->
    <div class="lozad" data-background-image-set="url('photo.jpg') 1x, url('photo@2x.jpg') 2x">
    </div>
    

    To change the delimiter that splits background images:

    <!-- custom delimiter for background images example -->
    <div
      class="lozad"
      data-background-image="/first/custom,image,path/image.png-/second/custom,image,path/image.png"
      data-background-delimiter="-"
    >
    </div>
    

    If you want to load the images before they appear:

    const observer = lozad();
    observer.observe();
    
    const coolImage = document.querySelector('.image-to-load-first');
    // ... trigger the load of a image before it appears on the viewport
    observer.triggerLoad(coolImage);
    

    Large image improvment

    Sometimes image loading takes a long time. For this case, you can add a placeholder background:

    <img class="lozad" data-placeholder-background="red" data-src="image.png">
    

    Lozad sets a placeholder background color of img element and users will see the fallback till the image loads.

    Example with picture tag

    Create a broken picture element structure.

    IE browser don't support picture tag! You need to set data-iesrc attribute (only for your picture tags) with source for IE browser

    data-alt attribute can be added to picture tag for use in alt attribute of lazy-loaded images

    <!-- For an element to be caught, add a block type that is different from the inline and some min-height for correct caught into view -->
    <picture class="lozad" style="display: block; min-height: 1rem" data-iesrc="images/thumbs/04.jpg" data-alt="">
        <source srcset="images/thumbs/04.jpg" media="(min-width: 1280px)">
        <source srcset="images/thumbs/05.jpg" media="(min-width: 980px)">
        <source srcset="images/thumbs/06.jpg" media="(min-width: 320px)">
        <!-- NO img element -->
        <!-- instead of img element, there will be the last source with the minimum dimensions -->
        <!-- for disabled JS you can set <noscript><img src="images/thumbs/04.jpg" alt=""></noscript> -->
    </picture>
    

    When lozad loads this picture element, it will fix it.

    If you want to use image placeholder (like low quality image placeholder), you can set a temporary img tag inside your picture tag. It will be removed when lozad loads the picture element.

    <picture class="lozad" style="display: block; min-height: 1rem" data-iesrc="images/thumbs/04.jpg" data-alt="">
        <source srcset="images/thumbs/04.jpg" media="(min-width: 1280px)">
        <source srcset="images/thumbs/05.jpg" media="(min-width: 980px)">
        <source srcset="images/thumbs/06.jpg" media="(min-width: 320px)">
        <!-- you can define a low quality image placeholder that will be removed when the picture is loaded -->
        <img src="data:image/jpeg;base64,/some_lqip_in_base_64==">
    </picture>
    

    Example with video

    <video class="lozad" data-poster="images/backgrounds/video-poster.jpeg">
        <source data-src="video/mov_bbb.mp4" type="video/mp4">
        <source data-src="video/mov_bbb.ogg" type="video/ogg">
    </video>
    

    Example with iframe

    <iframe data-src="embed.html" class="lozad"></iframe>
    

    That's all, just add the lozad class.

    Example toggling class

    <div data-toggle-class="active" class="lozad">
        <!-- content -->
    </div>
    

    The active class will be toggled on the element when it enters the browser’s viewport.

    Browser Support

    Available in latest browsers. If browser support is not available, then make use of polyfill.

    For IE11 support, please make use of these polyfills.

    FAQs

    Checkout the FAQ Wiki for some common gotchas to be aware of while using lozad.js

    Contribute

    Interested in contributing features and fixes?

    Read more on contributing.

    Changelog

    See the Changelog

    License

    MIT © Apoorv Saxena

    Show All