Skip to content
⚡️ <progressive-image> custom element
JavaScript CSS
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples docs(examples): add header description Feb 11, 2020
.editorconfig Initial commit Jan 31, 2020
.gitattributes Initial commit Jan 31, 2020
.gitignore Initial commit Jan 31, 2020 1.2.0 Feb 14, 2020
LICENSE Initial commit Jan 31, 2020 docs: savedata attribute mention slow connections Feb 11, 2020
constants.js fix: show dimension warning only if placeholder exists Feb 6, 2020
cypress.json chore: cypress setup Feb 6, 2020
example-2x.png docs: update example image Feb 1, 2020
index.js refactor: abstract constants Feb 5, 2020
package-lock.json 1.2.0 Feb 14, 2020
package.json chore(npm): add repository url Feb 14, 2020
progressive-image-element.css fix(css): contain aspect ratio for svg elements Feb 3, 2020
progressive-image-element.js feat: use connection test for default savedata value Feb 11, 2020

<progressive-image> element

A progressive image element

CI status npm version

Progressively enhance image placeholders once they are in the viewport.

  • Responsive lazy loading images
  • Save data option
  • No content reflow/layout shifting
  • No dependencies
  • Framework agnostic
progressive image element markup example


$ npm install progressive-image-element


  1. Include the script & stylesheet within your application
<!-- Include the stylesheet, this could be direct from the package or CDN -->
<link rel="stylesheet" href="" />

<!-- Include the custom element script, this could be direct from the package or CDN -->
<script src=""></script>


// Import the custom element script
import ProgressiveImageElement from 'progressive-image-element';
  1. Use the <progressive-image> element markup
  srcset="example-image-2x.jpg 2x, example-image-1x.jpg 1x"
  <!-- Make sure to specify image dimensions -->
  <img src="placeholder-image.jpg" width="300" height="200" alt="Image" />

The placeholder image should be a solid color placeholder, LQIP or SQIP that hint at the content of the progressive image before it loads.


  • src Specifies the image to display
  • srcset One or more image candidate strings
  • sizes Comma-separated list of source size descriptors
  • savedata Boolean attribute to load the images only after a click/tap on the placeholder image.
    By default enabled for slow connections (slow-2g|2g|3g).

Styling states

A CSS class loadable is present on <progressive-image> when the image is ready to load on user interaction (click). Used for slow connections or when the savedata attribute is present.

progressive-image.loadable { ... }

A CSS class [loading] is present on <progressive-image> while the image is loading.

progressive-image.loading { ... }

A CSS class .loaded is present on <img> children of <progressive-image> when the image was loaded.

progressive-image > img { opacity: 0; }
progressive-image > img.loaded { opacity: 1; }


Browser support

Browsers without native custom element support require a polyfill.


MIT © André Ruffert

You can’t perform that action at this time.