Lazy is a fast and lightweight delayed image and background loading plugin for jQuery. It is designed to speed up page loading times and decrease traffic to your users and customers by only loading the content in view. You can use Lazy in all scroll ways, from top-to-bottom, bottom-to-top, left-to-right and right-to-left. It does not only support images in <img/> tags, even backgrounds, supplied with css like background-image or other methods, are supported. Lazy can set an default image and a placeholder while loading and support retina displays.
How to use Lazy
1.) The basic usage of Lazy ist pretty easy. First of all you need to add a 'data-src' attribute to those images you want to load delayed and insert the image path you want to load over Lazy:
<img class="lazy" data-src="path_to/image.jpg" src="" />
2.) Next step is to add jQuery and the Lazy plugin to your page. Put this to <head> or somewhere you want:
3.) Start using Lazy by calling it after page load. You don't have to specify your elements. But for better performance, or different options, load your images over unique classes or any other jQuery selector:
Examples / Demo
Lazy will work with a wide range of browsers and support jQuery versions for years backwards. You can pick any version since jQuery 1.3.0 or greater.
There is no way to guarantee, that Lazy will work with all browser. But all i've tested worked great. If you find any problems in specific browsers, please let me know.
A list of all browser i've tested so far and Lazy worked well with:
|Internet Explorer||IE6, IE7, IE8, IE9, IE10, IE11|
|Firefox / Firefox Mobile||-|
|Chrome / Chrome Mobile||-|
|Safari / Safari Mobile||-|
You will also need jQuery itself to run Lazy.
By default, Lazy will load images on scroll or resize event, when an images enters the threshold/viewport. But there is also an option to load all images after a given delay time. You can set the time in milliseconds with the 'delay' parameter.
Lazy gives you the option to use callback functions, before, on, after and after all loading images. And if the image to load was not found, there is even a error callback. You can use them to create a better and more dynamic user experience or for further events.
The before and after load callback will have the current element as parameter. Because Lazy can even handle non-img tags, the on and error callbacks will always have an image object as parameter.
So the throttle will limit those calls in a given time. In this timespan only one call will be handled and all others will be ignored.
By default this option is activated and will work in background. You will not notice it. There are some parameters to change the timespan, for faster or slower handling, or deactivate the throttle:
Overview of all settings you can use to configure Lazy and change its behavior:
|chainable||boolean||true||By default Lazy is chainable and will return all elements. If set to 'false' Lazy will return the created plugin instance itself for further use. See example.|
|bind||string||load||If set to 'load' Lazy starts working directly after page load. If you want to use Lazy on own events set it to 'event'. See example.|
|threshold||integer||500||Amount of pixels below the viewport, in which all images gets loaded before the user sees them.|
|fallbackWidth||integer||2000||If the plugin could not determine a viewport width, it will use this fallback width.|
|fallbackHeight||integer||2000||If the plugin could not determine a viewport height, it will use this fallback height.|
|visibleOnly||boolean||false||Determine if only visible images should be load.|
|appendScroll||jQuery||window||An element to listen on for scroll events, useful when images are stored in a container. See example.|
|scrollDirection||string||both||Determines the handles scroll direction. Possible values are 'both', 'vertical' and 'horizontal'.|
|defaultImage||string||blank gif image||Base64 image string, set as default image source for every image without a predefined source attribute. See example.|
|placeholder||string||null||Base64 image string, set a background on every element as loading placeholder. See example.|
|delay||integer||-1||If you want to load all images at once after page load, then you can specify a delay time in milliseconds. See example.|
|combined||boolean||false||With this parameter, Lazy will combine the event driven and delayed image loading. See example.|
|attribute||string||data-src||Name of the image tag attribute, where the image path is stored. See example.|
|retinaAttribute||string||data-retina||Name of the image tag attribute, where the image path for optional retina image is stored. See example.|
|removeAttribute||boolean||true||Determine if the attribute should be removed from the image tag after loading. See example.|
|handledName||string||handled||Name of the image tag data attribute, to determine if image is already handled.|
|effect||string||show||Function name of the effect you want to use to show the loaded images, like 'show' or 'fadeIn'. See example.|
|effectTime||integer||0||Time in milliseconds the effect should use to view the image. See example.|
|enableThrottle||boolean||true||Throttle down the loading calls on scrolling event. See demonstration.|
|throttle||integer||250||Time in milliseconds the throttle will use to limit the loading calls.|
|enableQueueing||boolean||true||The queueing of events and calls is used the optimize the performance of Lazy with other scripts and libraries. It could be disable on side effects or to prioritize Lazy.|
|beforeLoad||object||null||Callback function, which will be called before the image gets loaded. Has current element as parameter. See example.|
|afterLoad||object||null||Callback function, which will be called after the image was loaded. Has current element as parameter. See example.|
|onError||object||null||Callback function, which will be called if the image could not be loaded. Has an image object as parameter. See example.|
|onFinishedAll||object||null||Callback function, which will be called after all images was loaded or returned an error. This callback has no parameter. See example.|