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.

Demo

There's a 10% chance to get a broken image.

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);

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.

// callback as soon as naturalWidth & naturalHeight are available (default)
$('#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
$('#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();

Within the callbacks the voila instance is always the first argument, the second one can be an image object.

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