README.md — Responsive Lightbox & Gallery 2.5.4

responsive-lightbox / assets / imagesloaded / README.md

responsive-lightbox / assets / imagesloaded Last commit date

LICENSE 3 years ago README.md 3 years ago imagesloaded.pkgd.js 3 years ago imagesloaded.pkgd.min.js 3 years ago

README.md

326 lines

1	# imagesLoaded
2
3	<p class="tagline">JavaScript is all like "You images done yet or what?"</p>
4
5	[](https://imagesloaded.desandro.comimagesloaded.desandro.com](https://imagesloaded.desandro.com](https://imagesloaded.desandro.com)
6
7	Detect when images have been loaded.
8
9	## Install
10
11	### Download
12
13	+ [](https://unpkg.com/imagesloaded@5/imagesloaded.pkgd.min.jsimagesloaded.pkgd.min.js](https://unpkg.com/imagesloaded@5/imagesloaded.pkgd.min.js](https://unpkg.com/imagesloaded@5/imagesloaded.pkgd.min.js) minified
14	+ [](https://unpkg.com/imagesloaded@5/imagesloaded.pkgd.jsimagesloaded.pkgd.js](https://unpkg.com/imagesloaded@5/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 [](https://api.jquery.com/category/deferred-object/jQuery Deferred object](https://api.jquery.com/category/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	[](https://codepen.io/desandro/pen/pjVMPBSee jQuery demo](https://codepen.io/desandro/pen/pjVMPB](https://codepen.io/desandro/pen/pjVMPB) or [](https://codepen.io/desandro/pen/avKooWvanilla JS demo](https://codepen.io/desandro/pen/avKooW](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	[](https://codepen.io/desandro/pen/avKoZLSee jQuery demo](https://codepen.io/desandro/pen/avKoZL](https://codepen.io/desandro/pen/avKoZL) or [](https://codepen.io/desandro/pen/vNrBGzvanilla JS demo](https://codepen.io/desandro/pen/vNrBGz](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	<!-- sponsored -->
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 [](https://browserify.org/Browserify](https://browserify.org/](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 [](https://github.com/desandro/imagesloaded/tree/v4.1.4imagesLoaded v4](https://github.com/desandro/imagesloaded/tree/v4.1.4](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 [](https://desandro.mit-license.org/MIT License](https://desandro.mit-license.org/](https://desandro.mit-license.org/). Have at it.
326