image-element

ImageElement

A lightweight library that provides additional methods for your images via the HTMLImageElement API.

Usage

The following methods will be available to you once you pass your <img> tag to the ImageElement constructor like this:

import ImageElement from 'image-element';
let imageEl = document.getElementByClassName('img')[0];
let image = new ImageElement(imageEl);

Lazy Loading an Image

The load() method is excellent for lazy-loading or loading images based on conditions (i.e loading low-quality images on lower bandwidths for mobile, for instance). It loads and shows an image using the url path specified in the custom attribute attr that you pass it. attr is a string denoting the custom attribute (on the element) that will contain the path of the image to be loaded or any image url you wish to load. The second argument callback should be a function that you want fired when the image is successfully fetched from the server, loaded and shown to the user.

<img data-lazy-src="path/to/my/image.jpg" src="" />

let imageEl = document.getElementByClassName('img')[0];
let image = new ImageElement(imageEl);

image.load('data-lazy-src').then(function () {
    // image done loading!
});

Loading Images Based on Viewport Size

Sometimes you may want to load images based on the user agent's viewport size (i.e. load higher resolution images when the viewport is large enough where hi-res images would be more appropriate).

The load() method accepts srcset's and loads images based on viewport size limits that are set. For instance, suppose you have the following <img> tag in the DOM and the viewport size is 1200 pixels wide, calling load() will load medium.jpg. See below.

<img my-srcset="medium.jpg 1000w, large.jpg 2000w" src="" />

let imageEl = document.getElementByClassName('img')[0];
let image = new ImageElement(imageEl);

image.load('my-srcset').then(function () {
    // medium.jpg has loaded because viewport size is less than 2000 pixels
});