progressive-image.js

demonstration | GitHub | npm | donate | @craigbuckler | craigbuckler.com

progressive-image.js implements a progressively-loaded image effect similar to those seen on Facebook and Medium. A very small blurred image is replaced with the full-resolution equivalent when the element is scrolled into view.

Please use the code as you wish. Tweet me @craigbuckler if you find it useful and consider donating toward development.

Benefits:

* saves unnecessary bandwidth
* fast loading, high performance, images loaded on view
* supports any image type (JPEG photographs are most appropriate)
* supports responsive images (srcset and sizes attributes)
* supports CSS background images
* supports native lazy loading and aspect ratios
* lightweight: 1,407 bytes of JavaScript, 407 bytes of optional CSS (minified)
* any CSS reveal effect can be applied
* no external dependencies - works with any framework
* makes up to three attempts if images fail to download
* works in all modern browsers (IE10+)
* progressively-enhanced to work in older browsers
* easy to use

View demonstration and full documentation...

Basic usage

Include the minified CSS and JavaScript anywhere in your page:

``html


`

or use npm and a bundler:

`sh
npm i progressive-image.js
`

Then add progressively-loaded images:

`html



`

where:

* full.jpg is the large image.
* tiny.jpg is a small preview image - typically 20px width.

Both images must have the same aspect ratio.

Refer to demo.html for full documentation, examples, options, and usage notes. It is also available as a CodePen demonstration page.

Version history

$3

* fixed page resize removing responsive srcset images

$3

* improved browser support verification
* more resilient to framework issues
* minor refactoring
* updated help and images
* bugfix: script now works in HTML

$3

* pageshow event for Single Page Apps
* more reliable MutationObserver
* class names applied to the preview are applied to the full image (except preview`)
* smaller, better performance
* no errors in older browsers
* updated usage notes, including native lazy loading

$3

* strict mode
* srcset and sizes attributes only set when available
* README and demo.html update

$3

* retries download after 3s and 6s (suggestion from cheuksing)
* continues to show preview if full image download fails
* autoprefixer update

$3

* Gulp.js minification
* published on npm, CDN information

$3

* added CSS background image support information

$3

* full image replaces preview in-place (PR from ftaiolivista)
* minor refactoring and simplification

$3

* permits any container element
* link to other URLs can be retained
* mutation observer event detects elements added via JavaScript
* minor performance tweaks

$3

* Initial commit