Skip to content

Latest commit

 

History

History
186 lines (128 loc) · 7.22 KB

README.markdown

File metadata and controls

186 lines (128 loc) · 7.22 KB
Raw

imagesLoaded

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

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

Calling

$(selector).imagesLoaded( [ callback ] );

selector

ImagesLoaded can be called on an elements with images within them, images directly, or a combination of both.

Example
// Calling on an element that may contain images
$('#content').imagesLoaded(fn);

// Calling on image elements directly
$('img').imagesLoaded(fn);

// Combination of both
$('#content, #gallery > img').imagesLoaded(fn);

[ callback ]

Callback argument can be a function, or an object map with deferred methods.

callback:function

Pass a function to be called when all images has finished with loading. This is the simplest way how to use imagesLoaded.

this

When executed, the callback function scope (this) is a jQuery object with element or set of elements on which the imagesLoaded has been called ($(selector)).

arguments

Callback function receives 3 arguments:

  • $images: Object jQuery object with all images
  • $proper: Object jQuery object with properly loaded images
  • $broken: Object jQuery object with broken images
Example
$('#my-container, .article img').imagesLoaded( function( $images, $proper, $broken ) {
    console.log( $images.length + ' images total have been loaded' );
    console.log( $proper.length + ' properly loaded images' );
    console.log( $broken.length + ' broken images' );
});

callback:object

To bind deferred methods before the determination process starts, pass an object with map of given method callbacks instead of a callback function. You can read more about these methods and their behavior in Deferred section below.

Example
$(selector).imagesLoaded({
    done: function ($images) {},
    fail: function ($images, $proper, $broken) {},
    always: function () {},
    progress: function (isBroken, $images, $proper, $broken) {}
});

If you are passing object with deferred methods, but you still want to use the simple callback functionality, use the callback property, like so:

$(selector).imagesLoaded({
    // ... deferred methods ...
    callback: function ($images, $proper, $broken) {}
});

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

// Save a deferred object with postponed determination process
var dfd = $('#my-container').imagesLoaded();

// 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( isBroken, $images, $proper, $broken ){
    // function scope (this) is a jQuery object with image that has just finished loading
    // callback provides four arguments:
    // isBroken: boolean value of whether the loaded image (this) is broken
    // $images:  jQuery object with all images in set
    // $proper:  jQuery object with properly loaded images so far
    // $broken:  jQuery object with broken images so far
    console.log( 'Loading progress: ' + ( $proper.length + $broken.length ) + ' out of ' + $images.length );
});

Important!: progress method should be always registered with callback:object argument, which ensures that it will be registered before the determination process starts. Otherwise you might run into an issue where by the time you register the progress method all images have been loaded, and there is nothing to report anymore.

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.

Behavior notes

Determination process

Every browser is handling image elements differently. We are trying to check for state in image attributes when possible & reliable, but in some browsers (especially older ones) we have to reset img.src attribute to re-trigger load/error events. That is the only possible way how to check for an image status, as well as differentiate between proper and broken images. We are resetting the src with blank image data-uri to bypass webkit log warning (thx doug jones).

Fortunately, since v2.0.0 we are in a state where imagesLoaded is both cross-browser reliable and fast, with only a few minor known issues.

Caching

The state of all once checked images is cached, so the calls repeated on the same images don't have to go through a determination process for each image again. Determining might be slow in older browsers in which we have to reset src, and also might introduce image flickering.

Image state is stored in $.data associated to that particular image DOM element and its src path (changing src of an image resets its cache). That means that everything is stored per page load, so you don't have to worry that temporarily unavailable images will be considered as broken on a next page load as well. Caching is just for a multiple calls within one page load.

If, however, you need it from some reason, you can remove this data from an image with:

$.removeData( img, 'imagesLoaded' );

Known issues

  • Unreliable differentiation between proper and broken images in Opera versions lower than 11 (market share ~0.1%), but callback still fires.
  • In IE (particularly in older versions) you might see images flicker as plugin has to refresh all src attributes to catch event types. Thankfully, this flickering is invisible most of the time.

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