minimal image lazy loader for jQuery
Latest commit e5153d0 Jun 25, 2011 Luca Belmondo fade-in animation improvements
Failed to load latest commit information. fade-in animation improvements Jun 25, 2011

jquery.lazydoll plugin

version: 0.0.7, 2011-06-25

Minimal jQuery lazy loader for images. The images are replaced with a placeholder, and loaded only when scrolling or resizing make them visible. The scroll event and the visibility can be referred to the window or to a given container.


// scroll referred to window

// again, scroll referred to window, but only some images are selected
$("#my-wrap img").lazydoll()

// scroll referred to $("#my-wrap")
$("#my-wrap img").lazydoll({
  container : "#my-wrap"

// if you want to show a loading icon (false by default)
$("#my-wrap img").lazydoll({
  container : "#my-wrap",
  show_loading : true

The img elements must have width and height specified, otherwise whimsical effects will occur.

Notice that the mechanism visually works without any modification to the markup, but this will not prevent the actual downloading of the images, or at least you can't count on it. To actually send the request for every single image only when it comes in sight, you will have to produce your html according to two rules:

  • specify the placeholder img as "src" attribute
  • put the actual url of the image in the attribute data-original-src


<img src="/my/real/image.jpeg" width="100" height="100" />

...will work, but the image will be fetched anyway from the server. Better would be to do:

<img src="/my_placeholder.gif" width="100" height="100" data-original-src="/my/real/image.jpeg" />

This will prevent your image from loading until it gets in sight.

In order to maintain compatibility with disabled javascript, you need to do:

<img src="/my_placeholder.gif" width="100" height="100" data-original-src="/my/real/image.jpeg" />
  <img src="/my/real/image.jpeg" width="100" height="100" />

...but the layout will of course be negatively affected, and if this is a concern you should evaluate some more complex solution, not showing the placeholder with javascript is disabled. This is beyond the scope of the plugin.

Default options

  • container : window; can be passed a selector-string, an HTML element, or a jQuery object
  • placeholder : "/images/grey.gif",
  • delay : 400 (loading of visible images starts only after the user stops scrolling for some time)
  • fade_in : true
  • fade_in_speed : 400

Loading icon options:

  • show_loading : false
  • icon_url : "/images/loading_icon.gif"
  • icon_width : 24
  • icon_height : 24

Notice that icon_width and icon_height must be specified, because Firefox, even version 4, can't detect the size of an image until it is actually inserted in the DOM.

Works on...

  • jQuery 1.4.4
  • firefox 4.0.1
  • chromium 11
  • validated with jshint, see options above, asi compatible


Affero GPL