progressive-image.js
demonstration, GitHub, npm, donate, @craigbuckler, craigbuckler.com
A lazy-loading progressive image system 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 donate toward development if you use it commercially.
- saves unnecessary bandwidth
- fast loading, high performance, images loaded on view
- supports any image type (JPEG photographs are most appropriate)
- supports responsive images (
srcsetandsizesattributes) - supports CSS background images
- small: 1,350 bytes of JavaScript, 440 bytes of 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
Usage instructions
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"></script>
CDN URLs are shown above but you can also npm i progressive-image.js to install via npm and use a bundler.
Basic example:
<a href="full.jpg" class="progressive replace">
<img src="tiny.jpg" class="preview" alt="image" />
</a>
Where:
full.jpgis the large image.tiny.jpgis a very small preview image - typically 20px in width saved with high JPEG compression. It be added to the page directly or inlined as a data URI.
Both images must have the same aspect ratio.
The full image is revealed when the preview is scrolled into view. After replacement, link-clicking is disabled and the HTML becomes:
<a href="full.jpg" class="progressive">
<img src="full.jpg" alt="image" />
</a>
If JavaScript or image loading fails, a blurred version of the preview image can be clicked to view the full image.
To retain the link or use an alternative container element, add a data-href attribute with the large image URL:
<a href="http://site.com/" data-href="full.jpg" class="progressive replace">
<img src="tiny.jpg" class="preview" alt="image" />
</a>
Responsive images of differing sizes and resolutions can be defined in the container link/element using data-srcset and data-sizes attributes which map to the standard srcset and sizes attributes:
<a href="small.jpg"
data-srcset="small.jpg 800w, large.jpg 1200w"
data-sizes="100vw"
class="progressive replace">
<img src="tiny.jpg" class="preview" alt="image" />
</a>
On replacement, the image code becomes:
<img src="small.jpg" srcset="small.jpg 800w, large.jpg 1200w" sizes="100vw" alt="image" />
Modern browsers will load large.jpg when the viewport width is 800px or greater.
Further examples, options and usage notes can be found on the demonstration page.
See How to Build Your Own Progressive Image Loader for information about the inspiration and techniques used in this component.
Version history
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