imagesLoaded

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

imagesloaded.desandro.com

Detect when images have been loaded.

Demo

Edit this example on CodePen or try the jQuery example.

Just to keep things interesting, there’s a 10% chance of adding a broken image.

Install

Get a packaged source file:

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

Or install via Bower: bower install imagesloaded

Or install via npm: npm 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.

You can require imagesloaded.pkgd.js.

requirejs( [
  'path/to/imagesloaded.pkgd.js',
], function( imagesLoaded ) {
  imagesLoaded( '#container', function() { ... });
});

Or, you can manage dependencies with Bower. Set baseUrl to bower_components and set a path config for all your application code.

requirejs.config({
  baseUrl: 'bower_components/',
  paths: { // path to your app
    app: '../'
  }
});

requirejs( [
  'imagesloaded/imagesloaded',
  'app/my-component.js'
], function( imagesLoaded, myComp ) {
  imagesLoaded( '#container', function() { ... });
});

Browserify

imagesLoaded works with Browserify.

npm install imagesloaded --save

var imagesLoaded = require('imagesloaded');

imagesLoaded( elem, function() {...} );

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.