LazyLoad is a fast, lightweight and flexible script that speeds up your web application by loading images only as they enter the viewport. LazyLoad is written in plain (vanilla) Javascript featuring the Intersection Observer API, it supports responsive images, it's SEO friendly and it has some other notable features.
Check out the LazyLoad website, in case you're reading this on GitHub.
Jump to:
Include the script | Recipes | Demos | Tips & tricks | API | Notable features
This documentation refers to the latest version of LazyLoad. Find here the documentation about version 8.x.
The recommended version of LazyLoad is 8.2. LazyLoad from 9 up will load all of your images at once on Safari and Internet Explorer since these browsers don't support the Intersection Observer API yet.
LazyLoad versions 10.3 and 8.2 support Internet Explorer 9 up. For more information, see the changelog.
From cdnjs
To include the recommended version:
<script src="https://cdnjs.cloudflare.com/ajax/libs/vanilla-lazyload/8.2.0/lazyload.min.js"></script>
To include the latest version of LazyLoad:
<script src="https://cdnjs.cloudflare.com/ajax/libs/vanilla-lazyload/10.3.1/lazyload.min.js"></script>
If you prefer to install LazyLoad locally in your project, you can either:
- download it from the
dist
folder The file you typically want to use islazyload.min.js
If you prefer the ES2015 version, uselazyload.es2015.js
- install it with
npm install --save vanilla-lazyload
- install it with
bower install vanilla-lazyload
It's possible to include it as an async
script, see Recipes below.
When to use: your lazy images are (normally) located in the body of a scrolling page.
HTML
<img alt="..."
data-src="../img/44721746JJ_15_a.jpg"
width="220" height="280">
Javascript
var myLazyLoad = new LazyLoad();
When to use: you want to lazily load responsive images using the
srcset
and thesizes
attribute.
HTML
<img data-src="/your/image1.jpg"
data-srcset="/your/image1.jpg 200w, /your/[email protected] 400w"
sizes="(min-width: 20em) 35vw, 100vw">
Javascript
var myLazyLoad = new LazyLoad();
When to use: 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 alt="Stivaletti" data-src="/your/image1.jpg">
</picture>
Javascript
var myLazyLoad = new LazyLoad();
When to use: 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 be sometimes 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.
When to use: 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.
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;
})();
When to use: when your scrolling container is not the main browser window, but a scrolling container.
HTML
<div id="scrollingPanel">
<img alt="Image description"
data-src="../img/44721746JJ_15_a.jpg"
width="220" height="280">
<!-- More images -->
</div>
Javascript
var myLazyLoad = new LazyLoad({
container: document.getElementById('scrollingPanel')
});
When to use: when your scrolling container is not the main browser window, and you have multiple scrolling containers.
HTML
<div id="scrollingPanel1">
<img alt="Image description"
data-src="../img/44721746JJ_15_a.jpg"
width="220" height="280">
<!-- More images -->
</div>
<div id="scrollingPanel2">
<img alt="Image description"
data-src="../img/44721746JJ_15_a.jpg"
width="220" height="280">
<!-- More images -->
</div>
Javascript
var myLazyLoad1 = new LazyLoad({
container: document.getElementById('scrollingPanel1')
});
var myLazyLoad2 = new LazyLoad({
container: document.getElementById('scrollingPanel2')
});
When to use: 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();
When to use: you want to lazily load
iframe
s 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"
});
When to use: 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-src="../img/44721746JJ_15_a.jpg"></div>
Javascript
var myLazyLoad = new LazyLoad({
elements_selector: ".lazy"
});
That's it. Whenever the element selected by elements_selector
is not an img
or an iframe
, LazyLoad puts the image found in the data-src
attribute in the background-image
of the element.
When to use: when you have a lot of scrolling containers in the page and you want to insantiate 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&txt=row_01_col_01&w=200&h=200">
<img src="" alt="Row 01, col 02" data-src="https://placeholdit.imgix.net/~text?txtsize=19&txt=row_01_col_02&w=200&h=200">
<!-- ... -->
</div>
<div class="horzContainer">
<img src="" alt="Row 02, col 01" data-src="https://placeholdit.imgix.net/~text?txtsize=19&txt=row_02_col_01&w=200&h=200">
<img src="" alt="Row 02, col 02" data-src="https://placeholdit.imgix.net/~text?txtsize=19&txt=row_02_col_02&w=200&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.
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 do it using the CSS classes set by LazyLoad when loading starts - see API.
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 |
---|---|---|
container |
The scrolling container, and the container of the elements in the elements_selector option. |
document |
elements_selector |
The string selector of the elements to load lazily, to be selected as descendants of the container object. |
"img" |
threshold |
The distance out of the viewport, expressed in pixel, before which to start loading the images | 300 |
data_src |
The name of the data attribute containing the original image source, excluding the "data-" part. E.g. if your data attribute is named "data-original" , just pass "original" |
"src" |
data_srcset |
The name of the data attribute containing the original image source set in either img and source tags, excluding the "data-" part. E.g. if your data attribute is named "data-original-set" , just pass "original-set" |
"srcset" |
class_loading |
The class applied to the elements while the loading is in progress. | "loading" |
class_loaded |
The class applied to the elements when the loading is complete | "loaded" |
class_error |
The class applied to the elements when the element causes an error | "error" |
callback_load |
A function to be called when an element was loaded. | null |
callback_error |
A function to be called when an element triggers an error. | null |
callback_set |
A function to be called when the src of an image is set in the DOM. | null |
You can call the following public methods on any instance of LazyLoad.
Method name | Effect |
---|---|
update() |
Tells LazyLoad that new lazy images have arrived in the container, so it must start to manage them |
destroy() |
Destroys the instance, unsetting instance variables and removing listeners. |
LazyLoad doesn't hide your images from search engines, even if you don't specify any initial src
you 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.