lukeed / onloaded

A tiny (350B) library to detect when images have loaded.

onloaded

A tiny (350B) library to detect when images have loaded

Demo

This module exposes three module definitions:

• ES Module: dist/onloaded.es.js
• CommonJS: dist/onloaded.js
• UMD: dist/onloaded.min.js

If using the UMD bundle, the library is exposed as onloaded globally.

Install

$ npm install --save onloaded

Usage

const onloaded = require('onloaded');

// passing a selector to `elem`
onloaded('#container > img', {
  onLoad(img) {
    img.className += ' loaded';
  },
  onError(img) {
    img.className += ' failed';
  },
  onProgress(val) {
    console.log(`I am ${ val * 100 }% complete!`);
  },
  onComplete(val, stats) {
    // val is always 1 ~~> 100%
    console.log('This callback always runs!');
    console.log(`  ${stats.loaded} loaded`);
    console.log(`  ${stats.failed} failed`);
    console.log(`  ${stats.total} total`);
  }
});

Note: Visit elem for other possibilities!

API

onloaded(elem, options)

elem

Type: String|Node|NodeList

You have several options here:

1. Pass a selector string to img element(s);

   onloaded('.container img', { ... });

2. Pass a reference to a specific <img /> DOM Node;

   var img = document.querySelector('.container img');
   onloaded(img, { ... });

3. Pass a reference to a multiple <img /> DOM Nodes;

   var imgs = document.querySelectorAll('.container img');
   onloaded(imgs, { ... });

4. Pass a reference to a container DOM Node that contains <img /> elements;

   var parent = document.querySelector('.container');
   onloaded(parent, { ... });

options.onError(node)

Type: Function

Callback whenever an image source failed to load. Receives the <img /> DOM node;

options.onLoad(node)

Type: Function

Callback whenever an image source sucessfully loads. Receives the <img /> DOM node;

options.onProgress(val, stats)

Type: Function

Callback whenever an image's network request has completed, regardless of success or failure.

Receives the current "progress" of completed requests as a decimal.

Also receives a stats object with loaded, failed, and total keys.

options.onComplete(val, stats)

Type: Function

Callback when all network requests have completed, regardless of success or failure.

Receives the "progress" as its first parameter. This will always equal 1.

Also receives a stats object with loaded, failed, and total keys.

License

MIT © Luke Edwards

onloaded's Issues

[RFC] Listen to CSS Background Images

If this lands, it will be a 2.0 release & thus will be the distinguishing feature between v1 and v2.

Most of the time when I'm trying to do a fair bit of animating, it's never on a <img/> directly. It's nearly always on a <div> with a background-image style property.

In those cases, I'd (presumably) like to know when the image has completely downloaded before I begin the non-critical animation. IMO, it's far worse to have something fly/scale in, only to be partially loaded and/or lag the browser while it tries to pain the image and animate at the same time.

Here's how it would look, I think:

// load all <div>s' background-images
onloaded('.slide > div', { background:true });

// load the background-images on .container's .slide nodes
onloaded('.container', { background:'.slide' });

I'm only guessing, but doing so may add roughly ~100-200 bytes, which is a significant increase since 1.0 is only 350 bytes.

Please cast your vote below 😆