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:

<script type="text/javascript" src="jquery.min.js"></script> <script type="text/javascript" src="jquery.lazy.min.js"></script>

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:

// javascript code jQuery(document).ready(function() { jQuery("img.lazy").lazy(); });


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:


  name version
Internet Explorer Internet Explorer IE6, IE7, IE8, IE9, IE10, IE11
Firefox Firefox / Firefox Mobile -
Chrome Mobile Chrome / Chrome Mobile -
Safari Safari / Safari Mobile -
Android Android Browser -



You can find all releases, files and examples on GitHub. If you want to get into the code feel free to use the source file. For productive usage you should take the minified version.

You will also need jQuery itself to run Lazy.

I would like to get your feedback!


Delayed Loading

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.

// javascript code jQuery(document).ready(function() { jQuery("img.lazy").lazy({ delay: 2000 }); });



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.

// javascript code jQuery("img.lazy").lazy({ beforeLoad: function(element) { element.removeClass("lazy"); }, afterLoad: function(element) { element.removeClass("loading").addClass("loaded"); }, onError: function(element) { console.log("image loading error: " + element.attr("src")); }, onFinishedAll: function() { console.log("finished loading all images"); }, });



The throttle function helps to decrease unnecessary function calls through scroll or resize events. On this events the trigger gets called many, many times in a second. But there is no need to handle all of this event triggers at once. To many calls can slow down the javascript engine and brings no advantages for the user.

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:

// javascript code jQuery("img.lazy").lazy({ enableThrottle: true, throttle: 250 });



Overview of all settings you can use to configure Lazy and change its behavior:


name type default description
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.