progressive-image-loader

    1.0.1 • Public • Published

    100% test coverage

    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

    Keywords

    none

    Install

    npm i progressive-image-loader

    DownloadsWeekly Downloads

    0

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    40 kB

    Total Files

    19

    Last publish

    Collaborators

    • tylerjpeterson