Skip to content
A JavaScript library to load images progressively 🌇
JavaScript CSS
Branch: master
Clone or download
Pull request Compare This branch is even with thinker3197:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist
docs
src
.gitignore
CONTRIBUTING.md
LICENSE
README.md
bower.json
demo.gif
package.json

README.md

Progressively

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.

demo-image

Table of Contents

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

You can’t perform that action at this time.