Progressively

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.

Install
Usage
API
Contribute
License

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

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

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 on small screens

You can add a medium version via data-progressive-sm to reduce the filesize on mobile devices with small screens.

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

The medium quality will be used up to 600px screen-width. This breakpoint can be varied the following options.

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

onload

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,
  smBreakpoint: 600,
  imgload: function(elem) {
  console.log(elem);
},
afterload: 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.

balmainctf / progressively