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

Package Sidebar


npm i progressively

Weekly Downloads






Last publish


  • thinker3197