imagesloaded

What is imagesloaded?

The imagesloaded npm package is a JavaScript library that detects when images have been loaded in a webpage. It is useful for ensuring that all images are fully loaded before performing certain actions, such as initializing a gallery or applying layout adjustments.

What are imagesloaded's main functionalities?

Basic Usage

This feature allows you to detect when all images within a specified container have been loaded. The callback function is executed once all images are fully loaded.

const imagesLoaded = require('imagesloaded');

imagesLoaded('#container', function() {
  console.log('All images are loaded');
});

Handling Individual Image Load Events

This feature allows you to handle events for each individual image as it loads. You can use the 'progress' event to check the status of each image and perform actions accordingly.

const imagesLoaded = require('imagesloaded');

imagesLoaded('#container').on('progress', function(instance, image) {
  if (image.isLoaded) {
    console.log('Image loaded:', image.img.src);
  } else {
    console.log('Image failed to load:', image.img.src);
  }
});

Using Promises

This feature allows you to use promises with imagesloaded. You can use the 'then' method to execute code when all images are loaded and the 'catch' method to handle any errors if one or more images fail to load.

const imagesLoaded = require('imagesloaded');

imagesLoaded('#container').then(function(instance) {
  console.log('All images are loaded');
}).catch(function(instance) {
  console.log('One or more images failed to load');
});

Other packages similar to imagesloaded

jquery

jQuery is a fast, small, and feature-rich JavaScript library. It makes things like HTML document traversal and manipulation, event handling, and animation much simpler with an easy-to-use API. While not specifically designed for image loading, jQuery can be used to achieve similar functionality with custom code.

masonry-layout

Masonry is a JavaScript grid layout library. It arranges elements vertically, positioning each element in the next open spot in the grid. Masonry can be used in conjunction with imagesloaded to create dynamic, responsive layouts that adjust once all images are loaded.

flickity

Flickity is a JavaScript library for creating touch, responsive, flickable carousels. It includes built-in support for detecting when images are loaded, making it a good alternative for use cases that involve image carousels.

README

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://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.