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.
This project uses node and npm. Go check them out if you don't have them locally installed.
$ npm install --save-dev progressively
Alternatively you can use Bower.
$ bower install progressively
Then 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 unpkg:
<script src="https://unpkg.com/progressively/dist/progressively.min.js"></script>
You can find the library on window.progressively
.
You also need to embed the css file at your page.
<link rel="stylesheet" href="https://unpkg.com/progressively/dist/progressively.min.css">
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.
<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.
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: Function
Arguments: None
The afterload
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 imgload
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,
imgload: function(elem) {
console.log(elem);
},
afterload: 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.