pre-loader

Event-driven sequential image preloading and lazyloading in vanilla js.

Installing

Either download it

...or, clone the repo:

$ git clone https://github.com/DimitarChristoff/pre-loader.git
...
$ cd pre-loader

...or use bower:

$ bower install pre-loader --save

Basic use

Load an array, get a functional callback when done:

// under a normal browser
new preLoader(/*Array*/images, /*Object*/options/);
 
// AMD with requireJS
require(['../js/pre-loader'], function(preLoader){
    new preLoader(/*Array*/images, /*Object*/options/);
});

NOTE: if RequireJS or any other AMD-compatible loader is available, pre-loader will not go to the global object but define itself as an AMD module that can be required.

Options

The options object you can pass to the constructor supports 5 different keys.

{
    // use a single pipeline, default: false
    pipeline: false,
    // auto start loading when instantiated
    auto: true,
    // optional function to call on each image
    onProgress: function(src, imageEl, index){},
    // optional function to call when all done
    onComplete: function(loaded, errors){},
    // optional function to call when an error happens
    onError: function(src){}
};

Example

The most basic example to prime the cache with 2 images:

new preLoader(['image1.jpg', 'http://domain.com/image2.jpg'], {
    onComplete: function(loaded, errors){
        console.log('cache primed with:', loaded);
        errors && errors.length && console.log('these failed:', errors);
    }
});

Progress reporting

Loading an array of images, firing a callback with each one and in the end:

new preLoader(['image1.jpg', 'http://domain.com/image2.jpg'], {
    onProgress: function(src, element, index){
        if (element){
            console.log|('loaded ' + src);
            // gets optional reference to element you can use:
            // document.appendChild(element);
        }
        else {
            console.log('failed ' + src);
        }
 
        // output some stats
        var donePercent = Math.floor((100 / this.queue.length) * this.completed.length);
        console.log(donePercent + '% completed', this.completed.length + this.errors.length + ' / ' + this.queue.length + ' done');
    },
    onComplete: function(loaded, errors){
        console.log('cache primed with:', loaded);
        errors && errors.length && console.log('these failed:', errors);
    }
});

Pipeline vs parallel

Optionally, you can control how the loading takes place. You can either let the browser resolve the resource handling or you could stick to using a single thread with pipelining (each image that completes calls the next one in the stack).

new preLoader(['image1.jpg', 'http://domain.com/image2.jpg'], {
    // enable a single pipeline
    pipeline: true,
    onComplete: function(list, errors){
        // this will take longer but won't waste resources.
    }
});

Waterfall with pipeline enabled:

Waterfall with parallel downloading enabled:

For more info, see the example folder or look at http://jsfiddle.net/dimitar/mFQm6/

Lazy loading of images

Lazy loading works based upon existing DOM img elements with a data-preload attribute, pointing to the image to load.

eg.

<img src="loading.gif" data-preload="images/real-image.jpg" />
<script>
    // go with defaults, we're good.
    var instance = preLoader.lazyLoad();
</script> 

The lazyLoad method accepts arguments to the normal preLoader constructor and additionally, a selector property that defaults to img[data-preload]. It will return an instance and all the callbacks will fire as expected. When an image matches the DOM element, it will set the src property and remove the data-preload attribute.