ozzie00 / imagesloaded

jQuery is all like "You images done yet or what?"

imagesLoaded

http://desandro.github.com/imagesloaded/

A small jQuery plugin that triggers a callback after all the selected/child images have been loaded. Because you can't do .load() on cached images.

Basic usage

$('#my-container').imagesLoaded( function( $images, $proper, $broken ) {
  // callback provides three arguments:
  // $images: the jQuery object with all images
  // $proper: the jQuery object with properly loaded images
  // $broken: the jQuery object with broken images
  // `this` is a jQuery object of container
  console.log( $images.length + ' images total have been loaded in ' + this );
  console.log( $proper.length + ' properly loaded images' );
  console.log( $broken.length + ' broken images' );
});

You can call imagesLoaded on a set of images as well.

$('.article img').imagesLoaded( myFunction );

Deferred

As of v1.2.0, imagesLoaded returns jQuery deferred object.

Behaviour

Resolved: deferred is resolved when all images have been properly loaded

Rejected: deferred is rejected when at least one image is broken

Notified: deferred is notified every time an image from stack has finished loading

Usage

var dfd = $('#my-container').imagesLoaded(); // save a deferred object

// Always
dfd.always( function(){
  console.log( 'all images has finished with loading, do some stuff...' );
});

// Resolved
dfd.done( function( $images ){
  // callback provides one argument:
  // $images: the jQuery object with all images
  console.log( 'deferred is resolved with ' + $images.length + ' properly loaded images' );
});

// Rejected
dfd.fail( function( $images, $proper, $broken ){
  // callback provides three arguments:
  // $images: the jQuery object with all images
  // $proper: the jQuery object with properly loaded images
  // $broken: the jQuery object with broken images
  console.log( 'deferred is rejected with ' + $broken.length + ' out of ' + $images.length + ' images broken' );
});

// Notified
dfd.progress( function( total, loaded, proper, broken ){
  // callback provides four integer arguments:
  // total:  number of total images in set
  // loaded: number of all loaded images so far
  // proper: number of properly loaded images so far
  // broken: number of broken images so far
  console.log( 'Loading progress: ' + ( Math.round( ( loaded * 100 ) / total ) ) + '%' );
});

Requirements

Deferred is being used only when present, so having older versions of jQuery doesn't break the plugin, just removes the functionality. For using any Deferred method, you need jQuery v1.5 and higher. For using Deferred progress method, you need jQuery v1.7 and higher. For availability of other Deferred methods, read the jQuery Deferred object documentation.

Contribute

It ain't easy knowing when images have loaded. Every browser has its own little quirks that make this a difficult task to develop a cross-browser solution. Pull requests, testing, issues, and commentary are all highly encouraged (pleasepleaseplease) and very much appreciated.

Contributors

• View contributors
• ajp
• Oren Solomianik