Notorious Puppy Memes

    imagesloaded
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/imagesloaded package

    5.0.0 • Public • Published

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

    Package managers

    Install via npm: npm install imagesloaded

    Install via Yarn: yarn add imagesloaded

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

    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

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

    Browser support

    • Chrome 49+
    • Firefox 41+
    • Edge 14+
    • iOS Safari 8+

    Use imagesLoaded v4 for Internet Explorer and other older browser support.

    Development

    Development uses Node.js v16 with npm v8

    nvm use

    MIT License

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

    Install

    npm i imagesloaded

    DownloadsWeekly Downloads

    211,190

    Version

    5.0.0

    License

    MIT

    Unpacked Size

    36.9 kB

    Total Files

    6

    Last publish

    Collaborators

    • desandro