Table of Contents
$ npm install --save progressively
Alternatively you can use Bower.
$ bower install progressively
// using ES6 modules // using CommonJS modulesvar progressively =
The UMD build is also available on CDN:
<!-- or -->
Once loaded, you can access the library on
You also need to embed the css file at your page
<!-- or -->
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.
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
Use as bg-image
You can also use progressively for background-images. Simply use
progressive__bg instead of
init() API has a few options
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 function sets the timout value for images to start load asynchronously. Ideally it's value should be low.
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 function is callback function which executes when all images have loaded. It is fired when all the image elements have 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 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
See the contributing file for instructions.