Naively Programmable Module


    1.2.5 • Public • Published


    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.


    Table of Contents


    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=""></script>
    <!-- or -->
    <script src=""></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="">
    <!-- or -->
    <link rel="stylesheet" href="">


    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">

    And initiate the script.


    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">

    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>



    The init() API has a few options


    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.


    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.


    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).


    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.


    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.

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


    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.


    See the contributing file for instructions.


    MIT license © Ashish


    npm i progressively

    DownloadsWeekly Downloads






    Last publish


    • thinker3197