imagesLoaded

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

imagesloaded.desandro.com

Detect when images have been loaded.

Install

Download

• imagesloaded.pkgd.min.js minified
• imagesloaded.pkgd.js un-minified

CDN

<script src="https://npmcdn.com/[email protected]/imagesloaded.pkgd.min.js"></script>
<!-- or -->
<script src="https://npmcdn.com/[email protected]/imagesloaded.pkgd.js"></script>

Package managers

Install via npm: npm install imagesloaded

Install via Bower: bower install imagesloaded --save

jQuery

You can use imagesLoaded as a jQuery Plugin.

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

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

.imagesLoaded() returns a jQuery Deferred object. This allows you to use .always(), .done(), .fail() and .progress().

$('#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 );
  });

Vanilla JavaScript

You can use imagesLoaded with vanilla JS.

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

• elem Element, NodeList, Array, or Selector String
• options Object
• 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() {...});

Bind events with vanilla JS with .on(), .off(), and .once() methods.

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 );

Background

Detect when background images have loaded, in addition to <img>s.

Set { background: true } to detect when the element's background image has loaded.

// jQuery
$('#container').imagesLoaded( { background: true }, function() {
  console.log('#container background image loaded');
});

// vanilla JS
imagesLoaded( '#container', { background: true }, function() {
  console.log('#container background image loaded');
});

See jQuery demo or vanilla JS demo on CodePen.

Set to a selector string like { background: '.item' } to detect when the background images of child elements have loaded.

// jQuery
$('#container').imagesLoaded( { background: '.item' }, function() {
  console.log('all .item background images loaded');
});

// vanilla JS
imagesLoaded( '#container', { background: '.item' }, function() {
  console.log('all .item background images loaded');
});

See jQuery demo or vanilla JS demo on CodePen.

Events

always

// jQuery
$('#container').imagesLoaded().always( function( instance ) {
  console.log('ALWAYS - all images have been loaded');
});

// vanilla JS
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

// jQuery
$('#container').imagesLoaded().done( function( instance ) {
  console.log('DONE  - all images have been successfully loaded');
});

// vanilla JS
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

$('#container').imagesLoaded().fail( function( instance ) {
  console.log('FAIL - all images loaded, at least one is broken');
});

// vanilla JS
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 );
  }
});

Browserify

imagesLoaded works with Browserify.

npm install imagesloaded --save

var imagesLoaded = require('imagesloaded');

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

Use .makeJQueryPlugin to make to use .imagesLoaded() jQuery plugin.

var $ = require('jquery');
var imagesLoaded = require('imagesloaded');

// provide jQuery argument
imagesLoaded.makeJQueryPlugin( $ );
// now use .imagesLoaded() jQuery plugin
$('#container').imagesLoaded( function() {...});

Webpack

Install imagesLoaded and imports-loader with npm.

npm install imagesloaded imports-loader

In your config file, webpack.config.js, use the imports loader to disable define and set window for imagesloaded.

module.exports = {
  module: {
    loaders: [
      {
        test: /imagesloaded|ev\-emitter/,
        loader: 'imports?define=>false&this=>window'
      }
    ]
  }
};

(This hack is required because of an issue with how Webpack loads dependencies. +1 this issue on GitHub to help get this issue addressed.)

You can then require('imagesloaded').

// main.js
var imagesLoaded = require('imagesLoaded');

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

Use .makeJQueryPlugin to make .imagesLoaded() jQuery plugin.

// main.js
var imagesLoaded = require('imagesLoaded');
var jQuery = require('jquery');

// provide jQuery argument
imagesLoaded.makeJQueryPlugin( $ );
// now use .imagesLoaded() jQuery plugin
$('#container').imagesLoaded( function() {...});

Run webpack.

webpack main.js bundle.js

RequireJS

imagesLoaded works with RequireJS.

You can require imagesloaded.pkgd.js.

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

Use .makeJQueryPlugin to make .imagesLoaded() jQuery plugin.

requirejs( [
  'jquery',
  'path/to/imagesloaded.pkgd.js',
], function( $, imagesLoaded ) {
  // provide jQuery argument
  imagesLoaded.makeJQueryPlugin( $ );
  // now use .imagesLoaded() jQuery plugin
  $('#container').imagesLoaded( function() {...});
});

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() { ... });
});

Browser support

• IE9+
• Android 2.3+
• iOS Safari 4+
• All other modern browsers

Use imagesLoaded v3 for IE8 support.

MIT License

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