Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including @staaky/voila with all npm packages installed. Try it out:

var voila = require("@staaky/voila")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

@staaky/voila v1.5.2

A jQuery plugin that provides callbacks for images, letting you know when they've loaded.


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.


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


$(element).voila([options][, callback]);
// For example
$('#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():


Additional callbacks can be attached using always(), progress(), fail() and done():

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


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


Voilà is MIT Licensed.

By Nick Stakenburg

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free