@staaky/voila
v1.5.2
Published
A jQuery plugin that provides callbacks for images, letting you know when they've loaded.
Downloads
3
Maintainers
Readme
Voilà
Voilà is a jQuery plugin that provides callbacks for images, letting you know when they've loaded.
Voilà has an API inspired by imagesLoaded, extended with useful methods like abort()
and support for naturalWidth
and naturalHeight
in all browsers, which makes it compatible with IE6 & IE7. Multiple loading methods are supported, allowing callbacks to fire as soon as naturalWidth
is available, making Voilà faster than alternatives that wait for onload
to fire.
Install
Get a packaged source file:
Include Voilà below jQuery:
<script type="text/javascript" src="jquery.min.js"></script>
<script type="text/javascript" src="voila.pkgd.min.js"></script>
Alternatively Voilà can be installed using Bower or npm:
bower install voila
npm install @staaky/voila
Usage
$(element).voila([options][, callback]);
// For example
$('#container').voila(callback);
$('#container').voila({ method: 'onload' }, callback);
options
- Object - (optional) An object with Optionscallback
- Function - (optional) A function called when all images have been loaded
Using a callback is the same as using always()
:
$('#container').voila().always(callback);
Additional callbacks can be attached using always()
, progress()
, fail()
and done()
:
$('#container').voila()
.always(function(instance) {
console.log('ALWAYS - All images have finished loading');
})
.progress(function(instance, image) {
var status = image.isLoaded ? 'loaded' : 'broken';
console.log('PROGRESS - Image ' + status + ': ' + image.img.src);
})
.fail(function(instance) {
console.log('FAIL - All images finished loading, but some are broken');
})
.done(function(instance) {
console.log('DONE - All images finished loading succesfully');
});
Options
Options can be set as the first parameter.
method
- String - The loading method, the default is'onload'
which calls callbacks as soon asonload
fires. The alternative is'naturalWidth'
, which calls callbacks as soon asnaturalWidth
is available, images will have dimensions at that point but could still be rendering. Don't use'naturalWidth'
when changing thesrc
attribute of an image, it becomes unreliable at that point. Use'onload'
instead in those cases.
// callback as soon as naturalWidth & naturalHeight are available
$('#container').voila({ method: 'naturalWidth' }, function(instance) {
$.each(instance.images, function(i, image) {
var img = image.img;
console.log(img.src + ' = ' + img.naturalWidth + 'x' + img.naturalHeight);
});
});
// give images more time to render by waiting for onload (default)
$('#container').voila({ method: 'onload' }, function(instance) {
console.log('All images have finished loading');
});
API
A voila
instance can be stored, exposing some extra properties and functions:
var voila = $('#container').voila();
voila.images
- Array - Contains animage
object for eachimg
element foundvoila.abort()
- Aborts all callbacksvoila.always(callback)
- Add a callback called after all images finished loadingvoila.progress(callback)
- Add a callback called as each image finishes loadingvoila.fail(callback)
- Add a callback called if one or more images fail to loadvoila.done(callback)
- Add a callback called after all images have succesfully loaded
Within the callbacks the voila
instance is always the first argument, the second one can be an image
object.
image.img
ImageElement - Theimg
element as found in the DOMimage.isLoaded
Boolean -true
when succesfully loaded
Here's how to find out which images have succesfully loaded within the always callback:
$('#container').voila(function(instance) {
$.each(instance.images, function(i, image) {
var status = image.isLoaded ? 'loaded' : 'broken';
console.log(status + ': ' + image.img.src);
});
});
License
Voilà is MIT Licensed.