progressive-image-loader v1.0.1

progressiveImageLoader

Progressively load images from a queue, or based on viewport proximity.

This module exports two classes to provide progressive image loading for image elements and elements with a CSS background-image. Both classes use the queue module to provide queue management and concurrency. QueueLoader retrieves all DOM elements with the data attribute passed as the selectorAttribute option, and processes the queue in the order the elements were retrieved.

ScrollLoader augments QueueLoader, uses the ScrollTrack module, and differs from QueueLoader by only adding elements to the queue when they enter the viewport. This behavior can be modified to begin loading when an element is a certain distance away from the viewport by passing an offset value (which is passed to the element's ScrollElement instance).

QueueLoader

Loads images progressively using a non-prioritized queue. Generally, elements towards the top of the DOM will load first as they are the first elements added to the queue. But this cannot be assumed to always be the case.

Options

Passed to constructor at instantiation.

Properties

Public instance properties.

Methods

Public instance methods.

Events

Instances fire the following events:

ScrollLoader

Loads images progressively based on an element's proximity to the visible viewport. Elements are still loaded into a queue to limit concurrency, but the queue will prioritize elements that have recently entered the viewport.

Options

All QueueLoader options plus offset:

Properties

All QueueLoader properties plus loaded:

Methods

All QueueLoader methods:

Events

All QueueLoader events:

Installation

Install via npm:

$ npm i progressive-image-loader

Usage

import {QueueLoader, ScrollLoader} from 'progressive-image-loader';

// Begin loading all images with a 5 second timeout
const queueLoader = new QueueLoader({timeout: 5000});
queueLoader.on('image-loaded', el => console.log(el));
queueLoader.on('complete', () => console.log('images loaded'));
queueLoader.load();

// Begin loading image when they are within 1 viewport of entering the viewport
const scrollLoader = new ScrollLoader({offset: '100vh'});
scrollLoader.on('image-loaded', el => console.log(el));
scrollLoader.on('complete', () => console.log('images loaded'));
scrollLoader.load();

Required CSS

You will need to include CSS on the page to support the functionality offered by these classes. The CSS should progressively enhance, therefore hiding of progressively-loaded images should be disabled if JavaScript is not supported. Assuming you have an initial no-js class on the html element, and replace it with a js class, the following CSS works assuming you use the default selector options:

html.js [data-progressive-image],
html.js [data-progressive-image] * {
	background-image: none !important;
	-webkit-mask-image: none !important;
	mask-image: none !important;
	opacity: 0;
}

html.js .progressive-image-animated,
html.js .progressive-image-animated * {
	will-change: opacity;
	opacity: 0;
	-webkit-transition: opacity 1s ease-out;
	transition: opacity 1s ease-out;
}

html.js .progressive-image-animated[data-progressive-image-loaded],
html.js .progressive-image-animated[data-progressive-image-loaded] *,
html.js .progressive-image-animated *[data-progressive-image-loaded],
html.js .progressive-image-animated *[data-progressive-image-loaded] * {
	opacity: 1;
}

Generating Customized CSS

You can generate the required SCSS/CSS using non-default values by running the css npm script, or by calling $(npm bin)/progressive-image-loader-css from the project this module is installed to. This will load a series of questions via an interactive prompt allowing you to customize the selectors and data attributes used by the instance, the progressive enhancement HTML class, the output format (css or scss), and the output location.

$ $(npm bin)/progressive-image-loader-css

$ npm run css