README.md

imagesLoaded

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

desandro.github.io/imagesloaded

Detect when images have been loaded.

Install

Get a packaged source file:

• imagesloaded.pkgd.min.js
• imagesloaded.pkgd.js

Or install via Bower:

bower install imagesloaded

Usage

imagesLoaded( elem, callback )
// you can use `new` if you like
new imagesLoaded( elem, callback )

• elem Element, NodeList, Array, or Selector String
• callback Function - function triggered after all images have been loaded

Using a callback function is the same as binding it to the always event (see below).

// element
imagesLoaded( document.querySelector('#container'), function( instance ) {
  console.log('all images are loaded');
});
// selector string
imagesLoaded( '#container', function() {...});
// multiple elements
var posts = document.querySelectorAll('.post');
imagesLoaded( posts, function() {...});

Events

imagesLoaded is an Event Emitter. You can bind event listeners to events.

var imgLoad = imagesLoaded( elem );
function onAlways( instance ) {
  console.log('all images are loaded');
}
// bind with .on()
imgLoad.on( 'always', onAlways );
// unbind with .off()
imgLoad.off( 'always', onAlways );

always

imgLoad.on( 'always', function( instance ) {
  console.log('ALWAYS - all images have been loaded');
});

Triggered after all images have been either loaded or confirmed broken.

• instance imagesLoaded - the imagesLoaded instance

done

imgLoad.on( 'done', function( instance ) {
  console.log('DONE  - all images have been successfully loaded');
});

Triggered after all images have successfully loaded without any broken images.

fail

imgLoad.on( 'fail', function( instance ) {
  console.log('FAIL - all images loaded, at least one is broken');
});

Triggered after all images have been loaded with at least one broken image.

progress

imgLoad.on( 'progress', function( instance, image ) {
  var result = image.isLoaded ? 'loaded' : 'broken';
  console.log( 'image is ' + result + ' for ' + image.img.src );
});

Triggered after each image has been loaded.

• instance imagesLoaded - the imagesLoaded instance
• image LoadingImage - the LoadingImage instance of the loaded image

Properties

LoadingImage.img

Image - The img element

LoadingImage.isLoaded

Boolean - true when the image has succesfully loaded

imagesLoaded.images

Array of LoadingImage instances for each image detected

var imgLoad = imagesLoaded('#container');
imgLoad.on( 'always', function() {
  console.log( imgLoad.images.length + ' images loaded' );
  // detect which image is broken
  for ( var i = 0, len = imgLoad.images.length; i < len; i++ ) {
    var image = imgLoad.images[i];
    var result = image.isLoaded ? 'loaded' : 'broken';
    console.log( 'image is ' + result + ' for ' + image.img.src );
  }
});

jQuery

If you include jQuery, imagesLoaded can be used as a jQuery Plugin.

$('#container').imagesLoaded( function() {
  // images have loaded
});

jQuery Deferred

The jQuery plugin returns a jQuery Deferred object. This allows you to use .always(), .done(), .fail() and .progress(), similarly to the emitted events.

$('#container').imagesLoaded()
  .always( function( instance ) {
    console.log('all images loaded');
  })
  .done( function( instance ) {
    console.log('all images successfully loaded');
  })
  .fail( function() {
    console.log('all images loaded, at least one is broken');
  })
  .progress( function( instance, image ) {
    var result = image.isLoaded ? 'loaded' : 'broken';
    console.log( 'image is ' + result + ' for ' + image.img.src );
  });

RequireJS

imagesLoaded works with RequireJS.

1. Install imagesLoaded and its dependencies
2. Update your RequireJS paths config so it can find those modules

requirejs.config({
  paths: {
    "eventie": "bower_components/eventie",
    "eventEmitter": "bower_components/eventEmitter"
  }
});

Contributors

This project has a storied legacy. Its current incarnation was developed by Tomas Sardyha @Darsain and David DeSandro @desandro.

MIT License

imagesLoaded is released under the MIT License. Have at it.