jQuery Lazy

What is Lazy?

Lazy is a fast, feature-rich, extensible and lightweight delayed content loading plugin for jQuery & Zepto.
It's designed to speed up page loading times and decrease traffic to your customers and users by only loading the content in view.

Designed for everything

Lazy supports images and backgrounds by default or any other content by plugins and custom loaders you like to implement.

It's a time saver

Lazy will decrease your development time and save traffic and loading times for your users and customers.

Scroll in every way

You can use Lazy in all vertical and horizontal scroll ways, it will only load the elements in threshold.

Mobile-friendly

Lazy works well on every tested mobile devices so far and supports retina and other high density displays as well.

Easy to customise

Lazy delivers a mighty configuration, many callbacks, public functions and custom loaders for full control on everything.

Fully free & open source

All sources are available on GitHub. Feel free to report bugs, ask for new features or even contribute to Lazy by yourself there!

Wide compatibility range

Features

Retina support

Fully open source

Scroll in all directions

Different callbacks

Implement custom loaders

Image placeholders

Use effects

Supports srcset

Throttled

Public functions

Delayed loading

Many instances

Use inside containers

Event support

Mighty configuration

Zepto compatible

Get Started

Installation

First of all, you will need a copy of jQuery or Zepto to use Lazy successfully in your project. If you get this you can install Lazy by different ways. Select your favorite below.

Basic Usage

Prepare the elements you want to lazy load.
By default add a data-src attribute to elements containing the loadable image or a data-loader attribute to elements witch shall use a plugin or custom loaders.

Simply attach a function to all callbacks you want to use by initialisation.
The element parameter is already an jQuery or Zepto object, so you can use it directly like element.addClass('handled').

$(".lazy").Lazy({
beforeLoad: function(element) {
// called before an elements gets handled
},
afterLoad: function(element) {
// called after an element was successfully handled
},
onError: function(element) {
// called whenever an element could not be handled
},
onFinishedAll: function() {
// called once all elements was handled
}
});

this is the current Lazy instance itself, so you can access everything like public function or configuration directly.

To access an instances public functions you can initialize them in an object oriented manner or grab the instance bind to every element by default.

// object oriented way, note the chainable parameter
var instance = $('.lazy').Lazy({ chainable: false });
// grab from elements
// only works well if you use same selector or a single instance overall
$('.lazy').Lazy();
var instance = $('.lazy').data("plugin_lazy");

The public functions config and addItems has some multiple functionality.

// 'config' can receive entries or set them to a new value
var value = instance.config('attribute');
instance.config('attribute', 'data-new-attribute');
// 'addItems' works with an jQuery object or any selector
// so these two lines have the exact same result
instance.addItems('img.new-items');
instance.addItems($('img.new-items'));

Custom Loaders

With the custom loaders option there is a powerful solution to load every contents the Lazy way.
The plugin will handle everything, you just create a loading method witch got triggered whenever the element hits the visibility threshold.
It's still possible to load images and custom loaders in the same Lazy instance.

Custom loaders can respond it's state back to the plugin.
This is highly necessary when you want to use one of the callbacks afterLoad, onError or onFinishedAll beside of your loaders.

Therefor you can either use jQuery's build-in functions load and error, or the response function, given as second parameter to your custom loaders.
Both ways do exactly the same, so you only had to choose one of them.

Note:
Zepto could not use the function load and may throw errors in the console.
Use the response function instead, if you're working with Zepto.

Create own Loader Plugins

The first parameter is the name of your plugin as string, or an array of names / aliases.
Second parameter is the loader function, witch is the same as in custom loaders.
Best practice is to wrap everything by an IIFE.

The optional second parameter gives you the ability to register a plugin by default to html element types.
When you do this, there is no need to set the data-loader attribute on each element you want to use this loader on.

But keep in mind, if you register an plugin on often used elements, like <div>, Lazy will try to handle each of them, every time!
If you want to do so anyway, use a most specific selector for jQuery or Zepto.

(function($) {
$.Lazy('av', ['audio', 'video'], function(element, response) {
// this plugin will automatically handle '<audio>' and '<video> elements,
// even when no 'data-loader' attribute was set on the elements
});
})(window.jQuery || window.Zepto);

Working with Zepto has a little special behavior.
Zepto could not use the function load on elements and may throw errors in the console.
Use the response function instead, if you're working with Zepto or writing a plugin for publicity.