djethales / progressively

A JavaScript library to load images progressively 🌇

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.

Table of Contents

• 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

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="https://cdn.jsdelivr.net/npm/progressively/dist/progressively.min.js"></script>
<!-- or -->
<script src="https://unpkg.com/progressively/dist/progressively.min.js"></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="https://cdn.jsdelivr.net/npm/progressively/dist/progressively.min.css">
<!-- or -->
<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 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">
</figure>

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

onLoad

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.

progressively.init({
  delay: 50,
  throttle: 300,
  smBreakpoint: 600,
  onLoad: function(elem) {
    console.log(elem);
  },
  onLoadComplete: 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.

License

MIT license © Ashish