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.

| option | type | description | |---|---|---| | loadedAttribute | String | Data attribute to add to element when image has loaded | | selectorAttribute | String | Data attribute to indicate image (src or background-image) should load progressively | | animateClass | String | Class to apply to element if image should fade in (animate) when loaded | | container | Element | Container element to limit scope of query against loadedAttribute | | concurrency | Number | Number of images to download concurrently | | animate | Boolean | Whether or not to fade in images once loaded | | timeout | Number | Timeout (in ms) before image loading is assumed to have failed, forcing element to appear without image-loaded callback firing |

Properties

Public instance properties.

| property | returns | description | |---|---|---| | isRunning | Boolean | Whether or not the instance is currently preloading images | | elements | Array | Collection of elements matching selectorAttribute option | | queue | Queue | Reference the the instance's queue |

Methods

Public instance methods.

| method | arguments | description | |---|---|---| | load() | | Begin progressively loading images | | setVisible(element) | Element | Manually make a progressively loaded image appear |

Events

Instances fire the following events:

| event | arguments | description | |---|---|---| | image-loaded | Element | Fires when an element's image is loaded | | complete | | Fires when entire queue has been processed |

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:

| option | type | description | |---|---|---| | offset | Object | Offset option passed to ScrollElement to determine when image loading begins | | loadedAttribute | String | Data attribute to add to element when image has loaded | | selectorAttribute | String | Data attribute to indicate image (src or background-image) should load progressively | | animateClass | String | Class to apply to element if image should fade in (animate) when loaded | | container | Element | Container element to limit scope of query against loadedAttribute | | concurrency | Number | Number of images to download concurrently | | animate | Boolean | Whether or not to fade in images once loaded | | timeout | Number | Timeout (in ms) before image loading is assumed to have failed, forcing element to appear without image-loaded callback firing |

Properties

All QueueLoader properties plus loaded:

| property | returns | description | |---|---|---| | loaded | Number | Number of elements loaded | | isRunning | Boolean | Whether or not the instance is currently preloading images | | elements | Array | Collection of elements matching selectorAttribute option | | queue | Queue | Reference the the instance's queue |

Methods

All QueueLoader methods:

| method | arguments | description | |---|---|---| | load() | | Begin progressively loading images | | setVisible(element) | Element | Manually make a progressively loaded image appear |

Events

All QueueLoader events:

| event | arguments | description | |---|---|---| | image-loaded | Element | Fires when an element's image is loaded | | complete | | Fires when entire queue has been processed |

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