1 | # imagesLoaded
|
2 |
|
3 | <p class="tagline">JavaScript is all like "You images done yet or what?"</p>
|
4 |
|
5 | [imagesloaded.desandro.com](https://imagesloaded.desandro.com)
|
6 |
|
7 | Detect when images have been loaded.
|
8 |
|
9 | ## Install
|
10 |
|
11 | ### Download
|
12 |
|
13 | + [imagesloaded.pkgd.min.js](https://unpkg.com/imagesloaded@5/imagesloaded.pkgd.min.js) minified
|
14 | + [imagesloaded.pkgd.js](https://unpkg.com/imagesloaded@5/imagesloaded.pkgd.js) un-minified
|
15 |
|
16 | ### CDN
|
17 |
|
18 | ``` html
|
19 | <script src="https://unpkg.com/imagesloaded@5/imagesloaded.pkgd.min.js"></script>
|
20 | <!-- or -->
|
21 | <script src="https://unpkg.com/imagesloaded@5/imagesloaded.pkgd.js"></script>
|
22 | ```
|
23 |
|
24 | ### Package managers
|
25 |
|
26 | Install via npm: `npm install imagesloaded`
|
27 |
|
28 | Install via Yarn: `yarn add imagesloaded`
|
29 |
|
30 | ## jQuery
|
31 |
|
32 | You can use imagesLoaded as a jQuery Plugin.
|
33 |
|
34 | ``` js
|
35 | $('#container').imagesLoaded( function() {
|
36 | // images have loaded
|
37 | });
|
38 |
|
39 | // options
|
40 | $('#container').imagesLoaded( {
|
41 | // options...
|
42 | },
|
43 | function() {
|
44 | // images have loaded
|
45 | }
|
46 | );
|
47 | ```
|
48 |
|
49 | `.imagesLoaded()` returns a [jQuery Deferred object](https://api.jquery.com/category/deferred-object/). This allows you to use `.always()`, `.done()`, `.fail()` and `.progress()`.
|
50 |
|
51 | ``` js
|
52 | $('#container').imagesLoaded()
|
53 | .always( function( instance ) {
|
54 | console.log('all images loaded');
|
55 | })
|
56 | .done( function( instance ) {
|
57 | console.log('all images successfully loaded');
|
58 | })
|
59 | .fail( function() {
|
60 | console.log('all images loaded, at least one is broken');
|
61 | })
|
62 | .progress( function( instance, image ) {
|
63 | var result = image.isLoaded ? 'loaded' : 'broken';
|
64 | console.log( 'image is ' + result + ' for ' + image.img.src );
|
65 | });
|
66 | ```
|
67 |
|
68 | ## Vanilla JavaScript
|
69 |
|
70 | You can use imagesLoaded with vanilla JS.
|
71 |
|
72 | ``` js
|
73 | imagesLoaded( elem, callback )
|
74 | // options
|
75 | imagesLoaded( elem, options, callback )
|
76 | // you can use `new` if you like
|
77 | new imagesLoaded( elem, callback )
|
78 | ```
|
79 |
|
80 | + `elem` _Element, NodeList, Array, or Selector String_
|
81 | + `options` _Object_
|
82 | + `callback` _Function_ - function triggered after all images have been loaded
|
83 |
|
84 | Using a callback function is the same as binding it to the `always` event (see below).
|
85 |
|
86 | ``` js
|
87 | // element
|
88 | imagesLoaded( document.querySelector('#container'), function( instance ) {
|
89 | console.log('all images are loaded');
|
90 | });
|
91 | // selector string
|
92 | imagesLoaded( '#container', function() {...});
|
93 | // multiple elements
|
94 | var posts = document.querySelectorAll('.post');
|
95 | imagesLoaded( posts, function() {...});
|
96 | ```
|
97 |
|
98 | Bind events with vanilla JS with .on(), .off(), and .once() methods.
|
99 |
|
100 | ``` js
|
101 | var imgLoad = imagesLoaded( elem );
|
102 | function onAlways( instance ) {
|
103 | console.log('all images are loaded');
|
104 | }
|
105 | // bind with .on()
|
106 | imgLoad.on( 'always', onAlways );
|
107 | // unbind with .off()
|
108 | imgLoad.off( 'always', onAlways );
|
109 | ```
|
110 |
|
111 | ## Background
|
112 |
|
113 | Detect when background images have loaded, in addition to `<img>`s.
|
114 |
|
115 | Set `{ background: true }` to detect when the element's background image has loaded.
|
116 |
|
117 | ``` js
|
118 | // jQuery
|
119 | $('#container').imagesLoaded( { background: true }, function() {
|
120 | console.log('#container background image loaded');
|
121 | });
|
122 |
|
123 | // vanilla JS
|
124 | imagesLoaded( '#container', { background: true }, function() {
|
125 | console.log('#container background image loaded');
|
126 | });
|
127 | ```
|
128 |
|
129 | [See jQuery demo](https://codepen.io/desandro/pen/pjVMPB) or [vanilla JS demo](https://codepen.io/desandro/pen/avKooW) on CodePen.
|
130 |
|
131 | Set to a selector string like `{ background: '.item' }` to detect when the background images of child elements have loaded.
|
132 |
|
133 | ``` js
|
134 | // jQuery
|
135 | $('#container').imagesLoaded( { background: '.item' }, function() {
|
136 | console.log('all .item background images loaded');
|
137 | });
|
138 |
|
139 | // vanilla JS
|
140 | imagesLoaded( '#container', { background: '.item' }, function() {
|
141 | console.log('all .item background images loaded');
|
142 | });
|
143 | ```
|
144 |
|
145 | [See jQuery demo](https://codepen.io/desandro/pen/avKoZL) or [vanilla JS demo](https://codepen.io/desandro/pen/vNrBGz) on CodePen.
|
146 |
|
147 | ## Events
|
148 |
|
149 | ### always
|
150 |
|
151 | ``` js
|
152 | // jQuery
|
153 | $('#container').imagesLoaded().always( function( instance ) {
|
154 | console.log('ALWAYS - all images have been loaded');
|
155 | });
|
156 |
|
157 | // vanilla JS
|
158 | imgLoad.on( 'always', function( instance ) {
|
159 | console.log('ALWAYS - all images have been loaded');
|
160 | });
|
161 | ```
|
162 |
|
163 | Triggered after all images have been either loaded or confirmed broken.
|
164 |
|
165 | + `instance` _imagesLoaded_ - the imagesLoaded instance
|
166 |
|
167 | ### done
|
168 |
|
169 | ``` js
|
170 | // jQuery
|
171 | $('#container').imagesLoaded().done( function( instance ) {
|
172 | console.log('DONE - all images have been successfully loaded');
|
173 | });
|
174 |
|
175 | // vanilla JS
|
176 | imgLoad.on( 'done', function( instance ) {
|
177 | console.log('DONE - all images have been successfully loaded');
|
178 | });
|
179 | ```
|
180 |
|
181 | Triggered after all images have successfully loaded without any broken images.
|
182 |
|
183 | ### fail
|
184 |
|
185 | ``` js
|
186 | $('#container').imagesLoaded().fail( function( instance ) {
|
187 | console.log('FAIL - all images loaded, at least one is broken');
|
188 | });
|
189 |
|
190 | // vanilla JS
|
191 | imgLoad.on( 'fail', function( instance ) {
|
192 | console.log('FAIL - all images loaded, at least one is broken');
|
193 | });
|
194 | ```
|
195 |
|
196 | Triggered after all images have been loaded with at least one broken image.
|
197 |
|
198 | ### progress
|
199 |
|
200 | ``` js
|
201 | imgLoad.on( 'progress', function( instance, image ) {
|
202 | var result = image.isLoaded ? 'loaded' : 'broken';
|
203 | console.log( 'image is ' + result + ' for ' + image.img.src );
|
204 | });
|
205 | ```
|
206 |
|
207 | Triggered after each image has been loaded.
|
208 |
|
209 | + `instance` _imagesLoaded_ - the imagesLoaded instance
|
210 | + `image` _LoadingImage_ - the LoadingImage instance of the loaded image
|
211 |
|
212 |
|
213 |
|
214 | ## Properties
|
215 |
|
216 | ### LoadingImage.img
|
217 |
|
218 | _Image_ - The `img` element
|
219 |
|
220 | ### LoadingImage.isLoaded
|
221 |
|
222 | _Boolean_ - `true` when the image has successfully loaded
|
223 |
|
224 | ### imagesLoaded.images
|
225 |
|
226 | Array of _LoadingImage_ instances for each image detected
|
227 |
|
228 | ``` js
|
229 | var imgLoad = imagesLoaded('#container');
|
230 | imgLoad.on( 'always', function() {
|
231 | console.log( imgLoad.images.length + ' images loaded' );
|
232 | // detect which image is broken
|
233 | for ( var i = 0, len = imgLoad.images.length; i < len; i++ ) {
|
234 | var image = imgLoad.images[i];
|
235 | var result = image.isLoaded ? 'loaded' : 'broken';
|
236 | console.log( 'image is ' + result + ' for ' + image.img.src );
|
237 | }
|
238 | });
|
239 | ```
|
240 |
|
241 | ## Webpack
|
242 |
|
243 | Install imagesLoaded with npm.
|
244 |
|
245 | ``` bash
|
246 | npm install imagesloaded
|
247 | ```
|
248 |
|
249 | You can then `require('imagesloaded')`.
|
250 |
|
251 | ``` js
|
252 | // main.js
|
253 | var imagesLoaded = require('imagesloaded');
|
254 |
|
255 | imagesLoaded( '#container', function() {
|
256 | // images have loaded
|
257 | });
|
258 | ```
|
259 |
|
260 | Use `.makeJQueryPlugin` to make `.imagesLoaded()` jQuery plugin.
|
261 |
|
262 | ``` js
|
263 | // main.js
|
264 | var imagesLoaded = require('imagesloaded');
|
265 | var $ = require('jquery');
|
266 |
|
267 | // provide jQuery argument
|
268 | imagesLoaded.makeJQueryPlugin( $ );
|
269 | // now use .imagesLoaded() jQuery plugin
|
270 | $('#container').imagesLoaded( function() {...});
|
271 | ```
|
272 |
|
273 | Run webpack.
|
274 |
|
275 | ``` bash
|
276 | webpack main.js bundle.js
|
277 | ```
|
278 |
|
279 | ## Browserify
|
280 |
|
281 | imagesLoaded works with [Browserify](https://browserify.org/).
|
282 |
|
283 | ``` bash
|
284 | npm install imagesloaded --save
|
285 | ```
|
286 |
|
287 | ``` js
|
288 | var imagesLoaded = require('imagesloaded');
|
289 |
|
290 | imagesLoaded( elem, function() {...} );
|
291 | ```
|
292 |
|
293 | Use `.makeJQueryPlugin` to make to use `.imagesLoaded()` jQuery plugin.
|
294 |
|
295 | ``` js
|
296 | var $ = require('jquery');
|
297 | var imagesLoaded = require('imagesloaded');
|
298 |
|
299 | // provide jQuery argument
|
300 | imagesLoaded.makeJQueryPlugin( $ );
|
301 | // now use .imagesLoaded() jQuery plugin
|
302 | $('#container').imagesLoaded( function() {...});
|
303 | ```
|
304 |
|
305 |
|
306 | ## Browser support
|
307 |
|
308 | + Chrome 49+
|
309 | + Firefox 41+
|
310 | + Edge 14+
|
311 | + iOS Safari 8+
|
312 |
|
313 | Use [imagesLoaded v4](https://github.com/desandro/imagesloaded/tree/v4.1.4) for Internet Explorer and other older browser support.
|
314 |
|
315 | ## Development
|
316 |
|
317 | Development uses Node.js v16 with npm v8
|
318 |
|
319 | ``` bash
|
320 | nvm use
|
321 | ```
|
322 |
|
323 | ## MIT License
|
324 |
|
325 | imagesLoaded is released under the [MIT License](https://desandro.mit-license.org/). Have at it.
|