justlazy.js

micro javascript image lazy loading library

build status

Why yet another lazy loading plugin?

Most of the existing javascript lazy loading plugins use extensive dependencies (e.g. jQuery) or support just the img-tag without responsive parts. This plugin is supposed to be a lightweight alternative. The main goals are:

test status

Usage

Too lazy for the details? Jump to the demo!

To lazy load an image, first of all a placeholder of your choice (e.g. span, div, ..) has to be defined. This placeholder itself is an html element which contains several data-attributes to provide the image information.

The library loads the images with javascript in the background and then replaces the whole placeholder with the image. You don't have to care about removing the styling or other relics of the placeholder. The replacement occurs in case of successful (within onload) and in case of faulty (within onerror) image loading.

Steps to do

  1. Define placeholder
  2. Register event

1. Define placeholder

The placeholder has to be defined in your html. The data-src and data-alt attributes are mandatory, the rest of them are optional. You can define as many placeholders as you need.

Attribute Description
data-src (mandatory) Source of the image
data-alt (mandatory) Alt text of the image, data-alt="" is allowed, but not recommended!
data-title Title of the image
data-srcset Responsive image source-set attribute

Example: 

<span data-src="default/image" data-alt="some alt text"
      data-srcset="small/image 600w, big/image 1000w"
      data-title="some title"
      class="justlazy-spinner">
</span>

As you can see, the default lazy loading spinner is provided by the justlazy-spinner class.

2. Register event

There are three possiblities to trigger the lazy loading of the image(s).

The most comfortable one registers an event listener for all placeholders with a specific css class (e.g. justlazy-spinner). The images will be loaded automatically if they become visible. The parameters are the css-class as string and optional options. (Demo 1) 

Justlazy.registerLazyLoadByClass(css-class[, options]);

If you need more flexibility, the next function accepts as first parameter the html object of the placeholder. So you can decide how to extract the placeholder objects out of the html. The parameters are the placeholder as object and options if you need them. (Demo 2) 

Justlazy.registerLazyLoad(placeholder[, options]);

The most flexible way is to use the last function, which has to be called manually to load the image. The advantage is, that you can use custom events (e.g. a sliding event of a gallery) to trigger the lazy loading. The parameters are placeholder as object and options. (Demo 3/4) 

Justlazy.lazyLoad(placeholder[, options]);

Parameters

css-class

The css-class is a string which has to be provided without the class selector dot as prefix.

Example: 

Justlazy.registerLazyLoadByClass("load-if-visible-placeholder");
placeholder
The placeholder has to be provided as plain javascript object.

Example: 

Justlazy.registerLazyLoad(document.getElementById("placeholder-1"));
options

The options are provided as object with following properties. All of them are optional and you can provide as many as you need.

Property Description
onloadCallback The function will be invoked if the image is properly loaded. After the invocation the placeholder will be replaced with the entirely loaded image.
onerrorCallback The function will be invoked if the image could not be loaded. After the invocation the placeholder will be replaced with the image tag. E.g. you can define a dummy or hide the broken image.
onreplaceCallback The function will be invoked after the placeholder is replaced with the image tag.
threshold The image is loaded the defined pixels before it appears on the screen. E.g. 200px before it becomes visible.

Example: 

Justlazy.registerLazyLoadByClass("load-if-visible-placeholder", {
    onloadCallback: function() {
        // do something after image loading (before replacement)
    },
    onerrorCallback: function() {
        // do something if an error occurs (before replacement)
    },
    onreplaceCallback: function() {
        // do something after replacement
    },
    threshold: 200
});

Demo

#1 lazy loading if images are visible

This example loads the images automatically if they become visible in the viewport and uses the event registration by class function. 

Justlazy.registerLazyLoadByClass("load-if-visible-placeholder");

#2 lazy loading images with pre-loading threshold

Usually the image will be loaded when it becomes visible in the viewport. If you set the threshold, the image will be pre-loaded due to the defined pixels. A threshold of 300 means, that the image will be loaded 300 pixels before it becomes visible for the user. This example uses the registration by placeholder function. 

var placeholders = document.querySelectorAll('.load-with-threshold-placeholder');
for (var i = 0; i < placeholders.length; ++i) {
    Justlazy.registerLazyLoad(placeholders[i], {
        threshold: 300
    });
}

#3 lazy loading with specific event (e.g. button click)

This example uses a button to trigger the image lazy loading manually. Instead of the click event, you can use any other event of your choice and register it via javascript. 

document.getElementById("custom-event-btn").onclick = function() {
    var imgPlaceholder = document.getElementById("custom-event-placeholder");
    Justlazy.lazyLoad(imgPlaceholder);

    return false;
};
lazy load image

#4: lazy loading with srcset attribute

This example demonstrates the usage of the srcset attribute. You just have to provide a placeholder with the data-srcset attribute. 

document.getElementById("srcset-btn").onclick = function() {
    var imgPlaceholder = document.getElementById("srcset-placeholder");
    Justlazy.lazyLoad(imgPlaceholder);

    return false;
};
lazy load responsive image

The comment in the lower right corner of the image indicates the size of the image, which has been loaded. The srcset attribute defines, that the small size is loaded if your screen width is lower or equals than 600 pixels. All screen sizes above will load the big image. If the browser doesn't support the srcset, the default image will be loaded.

If the big image is loaded once, you have to disable or clear the browser cache to see the small image again with a browser horizontal width <= 600px. Otherwise the cached big image will be used in all cases.

More lazy bridge images ..