imagesLoaded
JavaScript is all like "You images done yet or what?", (*1)
imagesloaded.desandro.com, (*2)
Detect when images have been loaded., (*3)
Install
Download
CDN
``` html
, (*4)
### Package managers
Install via npm: `npm install imagesloaded`
Install via Yarn: `yarn add imagesloaded`
## jQuery
You can use imagesLoaded as a jQuery Plugin.
``` js
$('#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()., (*5)
``` js
$('#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 );
});, (*6)
## Vanilla JavaScript
You can use imagesLoaded with vanilla JS.
``` 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)., (*7)
``` js
// 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() {...});, (*8)
Bind events with vanilla JS with .on(), .off(), and .once() methods.
``` js
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., (*9)
Set { background: true } to detect when the element's background image has loaded., (*10)
``` js
// jQuery
$('#container').imagesLoaded( { background: true }, function() {
console.log('#container background image loaded');
});, (*11)
// vanilla JS
imagesLoaded( '#container', { background: true }, function() {
console.log('#container background image loaded');
});, (*12)
[See jQuery demo](https://codepen.io/desandro/pen/pjVMPB) or [vanilla JS demo](https://codepen.io/desandro/pen/avKooW) on CodePen.
Set to a selector string like `{ background: '.item' }` to detect when the background images of child elements have loaded.
``` js
// 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., (*13)
Events
always
``` js
// jQuery
$('#container').imagesLoaded().always( function( instance ) {
console.log('ALWAYS - all images have been loaded');
});, (*14)
// vanilla JS
imgLoad.on( 'always', function( instance ) {
console.log('ALWAYS - all images have been loaded');
});, (*15)
Triggered after all images have been either loaded or confirmed broken.
+ `instance` _imagesLoaded_ - the imagesLoaded instance
### done
``` js
// 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., (*16)
fail
``` js
$('#container').imagesLoaded().fail( function( instance ) {
console.log('FAIL - all images loaded, at least one is broken');
});, (*17)
// vanilla JS
imgLoad.on( 'fail', function( instance ) {
console.log('FAIL - all images loaded, at least one is broken');
});, (*18)
Triggered after all images have been loaded with at least one broken image.
### progress
``` js
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., (*19)
-
instance imagesLoaded - the imagesLoaded instance
-
image LoadingImage - the LoadingImage instance of the loaded image
Properties
LoadingImage.img
Image - The img element, (*20)
LoadingImage.isLoaded
Boolean - true when the image has successfully loaded, (*21)
imagesLoaded.images
Array of LoadingImage instances for each image detected, (*22)
``` js
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 );
}
});, (*23)
## Webpack
Install imagesLoaded with npm.
``` bash
npm install imagesloaded
You can then require('imagesloaded')., (*24)
``` js
// main.js
var imagesLoaded = require('imagesloaded');, (*25)
imagesLoaded( '#container', function() {
// images have loaded
});, (*26)
Use `.makeJQueryPlugin` to make `.imagesLoaded()` jQuery plugin.
``` js
// main.js
var imagesLoaded = require('imagesloaded');
var $ = require('jquery');
// provide jQuery argument
imagesLoaded.makeJQueryPlugin( $ );
// now use .imagesLoaded() jQuery plugin
$('#container').imagesLoaded( function() {...});
Run webpack., (*27)
``` bash
webpack main.js bundle.js, (*28)
## Browserify
imagesLoaded works with [Browserify](https://browserify.org/).
``` bash
npm install imagesloaded --save
``` js
var imagesLoaded = require('imagesloaded');, (*29)
imagesLoaded( elem, function() {...} );, (*30)
Use `.makeJQueryPlugin` to make to use `.imagesLoaded()` jQuery plugin.
``` js
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., (*31)
Development
Development uses Node.js v16 with npm v8, (*32)
bash
nvm use, (*33)
MIT License
imagesLoaded is released under the MIT License. Have at it., (*34)
Wallogit.com
