Layzr.js

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.

• Demo Page

Usage

Follow these steps:

1. Install
2. Image Setup
3. Instance Creation

Install

Load the script.

Download it, install it with NPM, or install it with Bower.

<script src="layzr.js"></script>

CDN

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.

cdnjs

<script src="https://cdnjs.cloudflare.com/ajax/libs/layzr.js/{version}/layzr.min.js"></script>

jsDelivr

<script src="https://cdn.jsdelivr.net/layzr.js/{version}/layzr.min.js"></script>

Image Setup

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:

(Optional) Placeholders

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">

(Optional) Retina Support

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">

(Optional) Background Images

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>

Instance Creation

Create a new instance, and that's it!

var layzr = new Layzr();

Documentation for all options follows:

Options

Defaults shown below:

var layzr = new Layzr({
  container: null,
  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:

container

Customize the container that holds the elements to lazy load - using CSS selector syntax. This option may be useful when building single page applications.

Note that window is assumed to be the container if this option is set to null.

var layzr = new Layzr({
  container: null
});

selector

Customize the selector used to find elements to lazy load - using CSS selector syntax.

var layzr = new Layzr({
  selector: '[data-layzr]'
});

attr / retinaAttr

Customize the data attributes that image sources are taken from.

var layzr = new Layzr({
  attr: 'data-layzr',
  retinaAttr: 'data-layzr-retina'
});

bgAttr

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'
});

threshold

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
});

callback

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');
  }
});

Browser Support

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.

Colophon

• Site Design: Chris Allen
• Stock Photos: Unsplash
• Heading Links: heading-links.js
• Google Analytics Isogram: isogrammer
• Inspiration: Headroom.js, jQuery Unveil
• Education: Paul Lewis

License

MIT. © 2015 Michael Cavalea

Roadmap

• Add to CDN?