@staaky/voila

Voilà

Voilà is a jQuery plugin that provides callbacks for images, letting you know when they've loaded.

voila.nickstakenburg.com

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:

• voila.pkgd.js
• voila.pkgd.min.js

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 Options
• callback - 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 as onload fires. The alternative is 'naturalWidth', which calls callbacks as soon as naturalWidth is available, images will have dimensions at that point but could still be rendering. Don't use 'naturalWidth' when changing the src 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 an image object for each img element found
• voila.abort() - Aborts all callbacks
• voila.always(callback) - Add a callback called after all images finished loading
• voila.progress(callback) - Add a callback called as each image finishes loading
• voila.fail(callback) - Add a callback called if one or more images fail to load
• voila.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 - The img element as found in the DOM
• image.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.

---

By Nick Stakenburg