Naively Programmable Module

    progressively

    1.2.5 • Public • Published

    Progressively

    Travis Coveralls npm (scoped) David Standard - JavaScript Style Guide

    A JavaScript library to load images progressively

    It’s written entirely in JavaScript so it doesn’t depend on 3rd-party libraries like jQuery. It's super small, < 1.2kB when minified & gzipped! It will load the full-size images only when the user browses to that part of the page, saving bandwidth & server requests. It is compatible with all modern browsers. See the Demo.

    demo-image

    Table of Contents

    Install

    This project uses node and npm. Go check them out if you don't have them locally installed.

    $ npm install --save progressively

    Alternatively you can use Bower.

    $ bower install progressively

    With a module bundler like rollup or webpack, use as you would anything else:

    // using ES6 modules
    import progressively from 'progressively'
     
    // using CommonJS modules
    var progressively = require('progressively')

    The UMD build is also available on CDN:

    <script src="https://cdn.jsdelivr.net/npm/progressively/dist/progressively.min.js"></script>
    <!-- or -->
    <script src="https://unpkg.com/progressively/dist/progressively.min.js"></script>

    Once loaded, you can access the library on window.progressively.

    You also need to embed the css file at your page

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/progressively/dist/progressively.min.css">
    <!-- or -->
    <link rel="stylesheet" href="https://unpkg.com/progressively/dist/progressively.min.css">

    Usage

    Add a image to your HTML file setting the src attribute containing the lower quality image (< 20kb for ideal cases) and the data-progressive attribute holding the path/url to the high quality image.

    You can use lowly to create the images in low quality. Just run npm i -g lowly and then lowly image.jpg, after that a new image image-lowly.jpg will be created in the same directory of source image.

    <figure class="progressive">
      <img class="progressive__img progressive--not-loaded" data-progressive="img/highQualityImg.png" src="img/lowQualityImg.png">
    </figure>

    And initiate the script.

    progressively.init()

    See demo for examples.

    Use medium quality images for mobile devices

    You can add a medium resolution image via data-progressive-sm to reduce the filesize on mobile devices with small screens. The default breakpoint for loading progressive-sm image is 600 (in device independent pixels). Progressively will load the data-progressive-sm image when the user's device width is less than smBreakpoint value.

    <figure class="progressive">
      <img class="progressive__img progressive--not-loaded" data-progressive="img/highQualityImg.png" data-progressive-sm="img/mediumQualityImg.png" src="img/lowQualityImg.png">
    </figure>

    Use as bg-image

    You can also use progressively for background-images. Simply use progressive__bg instead of progressive__img:

    <div class="progressive__bg progressive--not-loaded" data-progressive="img/highQualityImg.png" data-progressive-sm="img/mediumQualityImg.png" style="background-image: url('img/lowQualityImg.png');"></div>

    API

    progressively.init(options)

    The init() API has a few options

    throttle

    Type: Number Default: 300

    The throttle is managed by an internal function that prevents performance issues from continuous firing of window.onscroll events. Using a throttle will set a small timeout when the user scrolls and will keep throttling until the user stops. The default is 300 milliseconds.

    delay

    Type: Number Default: 100 value

    The delay function sets the timout value for images to start load asynchronously. Ideally it's value should be low.

    smBreakpoint

    Type: Number Default: 600 value

    The loadImage function uses this value, to load images in a medium quality (if defined and if the user's viewport is smaller than smBreakpoint).

    onLoadComplete

    Type: Function Arguments: None

    The onLoadComplete function is callback function which executes when all images have loaded. It is fired when all the image elements have the *--is-loaded class.

    onLoad

    Type: Function Arguments: HTMLElement

    The onLoad function is invoked whenever an image elements finishes loading. It accepts HTMLElement as an argument which is the current element that is loaded.

    progressively.init({
      delay: 50,
      throttle: 300,
      smBreakpoint: 600,
      onLoad: function(elem) {
        console.log(elem);
      },
      onLoadComplete: function() {
        console.log('All images have finished loading!');
      }
    });

    progressively.render()

    Progressively has a render() method that can be used to make progressively poll your images when you're not scrolling. For instance in some case you want to render your images before/widthout scrolling down to the image, you can use render.

    Contribute

    See the contributing file for instructions.

    License

    MIT license © Ashish

    Install

    npm i progressively

    DownloadsWeekly Downloads

    416

    Version

    1.2.5

    License

    MIT

    Last publish

    Collaborators

    • thinker3197