Skip to content

A lazy-loading progressive image similar to those seen on Facebook and Medium.

License

Notifications You must be signed in to change notification settings

craigbuckler/progressive-image.js

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

30 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/progressive-image.js/dist/progressive-image.css">
<script src="https://cdn.jsdelivr.net/npm/progressive-image.js/dist/progressive-image.js" async></script>

or use npm and a bundler:

npm i progressive-image.js

Then add progressively-loaded images:

<a href="full.jpg" class="progressive replace">
  <img src="tiny.jpg" class="preview" alt="image" />
</a>

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

v1.6.1, 2 October 2021

  • fixed page resize removing responsive srcset images

v1.6.0, 3 July 2020

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

v1.5.0, 6 June 2020

  • 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

v1.4.1, 9 July 2019

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

v1.4.0, 24 June 2019

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

v1.3.0, 30 May 2019

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

v1.2.0, 13 April 2018

  • added CSS background image support information

v1.2.0, 9 April 2018

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

v1.1.0, 25 November 2017

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

v1.0.0, 16 January 2017

  • Initial commit

About

A lazy-loading progressive image similar to those seen on Facebook and Medium.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •