Lazy Load Plugin for jQuery

Lazy Load is a jQuery plugin written in JavaScript. It delays loading of images in long web pages. Images outside of viewport (visible part of web page) wont be loaded before user scrolls to them. This is opposite of image preloading.

Using Lazy Load on long web pages containing many large images makes the page load faster. Browser will be in ready state after loading visible images. In some cases it can also help to reduce server load.

Lazy Load is inspired by YUI ImageLoader Utility by Matt Mlinac.

For those in hurry there are several demo pages available: basic options, with fadein effect, noscript fallback, horizontal scrolling, horizontal scrolling inside container, vertical scrolling inside container, page with gazillion images and load images using timeout.

When checking the demos clear browser cache between each request. You can check what is actually loaded with developers console (Chrome and Safari), FireBug (Firefox) or HTTPHeaders (IE).

How to Use?

Lazy Load depends on jQuery. Include them both in end of your HTML code:

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

You must alter your HTML code. Put the place holder image into src attribute. Demo pages use 1×1 pixel grey gif. URL of the real image must be put into data-original attribute. It is good idea to give Lazy Loaded image a specific class. This way you can easily control which images plugin is binded to.

<img class="lazy" src="img/grey.gif" data-original="img/example.jpg"  width="640" heigh="480">

then in your code do:

$("img.lazy").lazyload();

This causes all images of class lazy to be lazy loaded. See the basic options demo.

Fallback for Non JavaScript Browsers

Practically everyone has JavaScript enabled. However there are cases when you want to show the real images even if request come from client which does not support JavaScript. Google crawlers are one good candidate. Google crawlers do not execute JavaScript but also seem to ignore noscript content. To degrade gracefully when JavaScript is not enabled you can include the real image tag inside <noscript> block.

<img class="lazy" src="img/grey.gif" data-original="img/example.jpg"  width="640" heigh="480">
<noscript><img src="img/example.jpg" width="640" heigh="480"></noscript>

To prevent both placeholder and the real image showing at the same time hide the place holder with css.

.lazy {
  display: none;
}

For JavaScript enabled browser you must enable displaying the placeholders when documents loads. This can be done at the same time when initializing the plugin.

$("img.lazy").show().lazyload();

All this is optional can should be done only if you want the plugin to degrade gracefully.

Setting Sensitivity

By default images are loaded when they appear on the screen. If you want images to load earlier you can set threshold parameter. Setting threshold to 200 causes image to load 200 pixels before it is visible.

$("img.lazy").lazyload({ threshold : 200 });

Event to Trigger Loading

Event can be any jQuery event such as click or mouseover. You can also use your own custom events such as sporty or foobar. Default is to wait until user scrolls down and image appears on the window. To prevent all images to load until their placeholder image is clicked you could do:

$("img.lazy").lazyload({ 
    event : "click"
});

Using Effects

By default plugin waits for image to fully load and calls show() to show it. You can use any effect you want. Following code uses fadeIn effect. Check how it works at effect demo page.

$("img.lazy").lazyload({ 
    effect : "fadeIn"
});

Images Inside Container

You can also use plugin for images inside scrolling container, such as div with scrollbar. Just pass the container as jQuery object. There is a demo for horizontal and vertical container.

#container {
    height: 600px;
    overflow: scroll;
}

$("img.lazy").lazyload({         
     container: $("#container")
});

When Images Are Not Sequential

After scrolling page Lazy Load loops though unloaded images. In loop it checks if image has become visible. By default loop is stopped when first image below the fold (not visible) is found. This is based on following assumption. Order of images on page is same as order of images in HTML code. With some layouts assumption this might be wrong. You can control loading behaviour with failure_limit option.

$("img.lazy").lazyload({ 
    failure_limit : 10
});

Setting failure_limit to 10 causes plugin to stop searching for images to load after finding 10 images below the fold. If you have a funky layout set this number to something high.

Delayed Loading of Images

Not exactly feature of Lazy Load but it is also possible to delay loading of images. Following code waits for page to finish loading (not only HTML but also any visible images). Five seconds after page is finished, below the fold images are loaded automatically. You can also check the delayed loading demo.

$(function() {          
    $("img:below-the-fold").lazyload({
        event : "sporty"
    });
});
$(window).bind("load", function() { 
    var timeout = setTimeout(function() {$("img.lazy").trigger("sporty")}, 5000);
}); 

Load Invisible Images

There are cases when you have invisible images. For example when using plugin in together with a large filterable list of items that can have their visibility state changed dynamically. To improve performance Lazy Load ignores hidden images by default. If you want to load hidden images set skip_invisible to false.

$("img.lazy").lazyload({ 
    skip_invisible : false
});

Download

Latest source or minified. Plugin has been tested with Safari 5.1, Firefox 3.6, Firefox 7.0, Firefox 8.0 on OSX and Firefox 3.0, Chrome 14 and IE 8 on Windows and Safari 5.1 on iOS 5 both iPhone and iPad.

When asking a question please include an URL to example page where the problem occurs. If you have longer code examples please use pastie.org

jquery.lazyload.js

jquery.lazyload.min.js

http://www.appelsiini.net/projects/lazyload