A small, fast, modern, and dependency-free library for lazy loading.
Lazy loading boosts page speed by deferring the loading of images until they're in (or near) the viewport. This library makes it completely painless - maximizing speed by keeping options to a minimum.
Load the script.
Download it, install it with NPM, or install it with Bower.
<script src="layzr.js"></script>
The script is also available via CDN.
In the examples below, replace {version}
with your desired version. Refer to the releases page for version info.
<script src="https://cdnjs.cloudflare.com/ajax/libs/layzr.js/{version}/layzr.min.js"></script>
<script src="https://cdn.jsdelivr.net/layzr.js/{version}/layzr.min.js"></script>
For each img
and/or iframe
you want to lazy load, put the src
in the data-layzr
attribute.
<img data-layzr="image/source">
<iframe data-layzr="media/source"></iframe>
This is the only required attribute. Advanced, optional configuration follows:
Include a placeholder, via the src
attribute.
Images without a placeholder - before they're loaded - may impact layout (no width/height), or appear broken.
<img src="optional/placeholder" data-layzr="image/source">
Include a retina (high-resolution) version of the image in the data-layzr-retina
attribute. This source will only be loaded if the devicePixelRatio is greater than 1.
Ensure the proper CSS is in place to display both regular and retina images correctly. This library handles the loading, but not the displaying, of elements.
<img data-layzr="image/source" data-layzr-retina="optional/retina/source">
Include the data-layzr-bg
attribute to load the source as a background image.
The data-layzr-bg
attribute should be valueless - the image source is still taken from the data-layzr
and data-layzr-retina
attributes.
<img data-layzr="image/source" data-layzr-bg>
(Optional) Hidden Images
Include the data-layzr-hidden
attribute to prevent an image from loading.
Removing this attribute will not load the image - the user will still need to scroll, and the element will still need to be in the viewport.
<img data-layzr="image/source" data-layzr-hidden>
Create a new instance, and that's it!
var layzr = new Layzr();
Documentation for all options follows:
Defaults shown below:
var layzr = new Layzr({
selector: '[data-layzr]',
attr: 'data-layzr',
retinaAttr: 'data-layzr-retina',
bgAttr: 'data-layzr-bg',
hiddenAttr: 'data-layzr-hidden',
threshold: 0,
callback: null
});
Explanation of each follows:
Customize the selector used to find elements to lazy load - using CSS selector syntax.
var layzr = new Layzr({
selector: '[data-layzr]'
});
Customize the data attributes that image sources are taken from.
var layzr = new Layzr({
attr: 'data-layzr',
retinaAttr: 'data-layzr-retina'
});
Customize the data attribute that loads images as a background.
var layzr = new Layzr({
bgAttr: 'data-layzr-bg'
});
hiddenAttr
Customize the data attribute that prevents images from loading.
var layzr = new Layzr({
hiddenAttr: 'data-layzr-hidden'
});
Adjust when images load, relative to the viewport. Positive values make elements load sooner.
Threshold is a percentage of the viewport height - think of it as similar to the CSS vh
unit.
// load images when they're half the viewport height away from the bottom of the viewport
var layzr = new Layzr({
threshold: 50
});
Invoke a callback function each time an image is loaded.
The image may not be fully loaded before the function is called. Detecting image load is inconsistent at best in modern browsers.
// in the callback function, "this" refers to the image node
var layzr = new Layzr({
callback: function() {
this.classList.add('class');
}
});
Layzr natively supports IE10+.
To add support for older browsers, consider including Paul Irish's polyfill for requestAnimationFrame.
There are currently no plans to include the polyfill in the library, in the interest of file size.
- Site Design: Chris Allen
- Stock Photos: Unsplash
- Heading Links: heading-links.js
- Google Analytics Isogram: isogrammer
- Inspiration: Headroom.js, jQuery Unveil
- Education: Paul Lewis
MIT. © 2015 Michael Cavalea
- Add to CDN?