JavaScripting

The definitive source of the best
JavaScript libraries, frameworks, and plugins.


  • ×

    Imagesloaded

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

    • 🔾74%Overall
    • 7,723
    • 17.9 days
    • 🕩1136
    • 👥13

    imagesLoaded

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

    imagesloaded.desandro.com

    Detect when images have been loaded.

    Install

    Download

    CDN

    <script src="https://unpkg.com/imagesloaded@4/imagesloaded.pkgd.min.js"></script>
    <!-- or -->
    <script src="https://unpkg.com/imagesloaded@4/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 successfully 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 with npm.

    npm install imagesloaded
    

    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 $ = 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.

    Show All