progressive-image.js demonstration

progressive-image.js implements a lazy-loading progressive image 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. Download from GitHub…

mountain cave



The preview image can be very small - perhaps 20px in width and saved with high JPEG compression. This typically results in an image less than 500 bytes in size. It be added to the page directly or inlined as a data URI using base-64 encoding.

The large image can be any size but should match the preview image's aspect ratio. For example, 20x15 can be scaled to 200x150, 400x300 or 1600x1200.

Basic example

The page must load the CSS and JavaScript. It can be placed anywhere on the page but, typically, the CSS is loaded in the <head> and the JS is loaded just before the closing </body> tag:

<link rel="stylesheet" href="css/progressive-image.min.css">
<script src="js/progressive-image.min.js"></script>

The simplest progressive image is a link to the full-size graphic around the preview. Note the progressive and replace classes on the link and the preview class on the image.

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

If image loading or JavaScript fails, a blurred version of the preview image can be clicked to view the full image:


When JavaScript runs successfully, the large image is revealed when the preview is scrolled into view. CSS3 effects are used to fade and zoom the image:


After replacement, the link click is disabled and resulting HTML will be:

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

Retain the link

If you require a responsive image to remain a real link, use the href for the address then add a data-href attribute with the large image URL:

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

Alternative container elements

If necessary, any HTML element can be used with a data-href attribute rather than a link, e.g.

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

Responsive images

Responsive images of differing sizes and resolutions can be defined in the container link/element using the data-srcset and data-sizes attributes which map to the standard srcset and sizes attributes, e.g.

<a href="small.jpg"
  data-srcset="small.jpg 800w, large.jpg 1200w"
  class="progressive replace">
  <img src="preview.jpg" class="preview" alt="image" />

(carriage returns added to aid legibility)

On replacement, the image code is transformed to:

<img src="small.jpg"
srcset="small.jpg 800w, large.jpg 1200w"
alt="image" />

Modern browsers will load large.jpg on screens of 800px width or greater.

Usage notes

  1. Works in all browsers from IE10 and above. IE10/11 will not blur the preview image. Older browsers fallback to click-to-view.
  2. The preview and full-size images must have identical aspect ratios, e.g. 20x10 and 1200x600.
  3. Only vertical scrolling is checked. All images in the horizontal plane will be loaded.
  4. Progressive images dynamically added to the page using JavaScript will be replaced if the browser supports MutationObserver.
  5. You may improve actual or perceived performance using data URIs to inline images or intrinsic placeholders.


All images in this demonstration have been sourced from and are credited to Alex Blăjan, Philippe Toupet, James Padolsey, Ashim D’Silva, and Levi Guzman.