<progressive-image> element

A progressive image element

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

Install

$ npm install progressive-image-element

Usage

Include the script & stylesheet within your application

<!-- Include the stylesheet, this could be direct from the package or CDN -->
<link rel="stylesheet" href="https://unpkg.com/progressive-image-element@latest/dist/progressive-image-element.css" />

<!-- Include the custom element script, this could be direct from the package or CDN -->
<script src="https://unpkg.com/progressive-image-element@latest/dist/index.js"></script>

// Import the custom element script
import ProgressiveImageElement from 'progressive-image-element';

Use the <progressive-image> element markup

<progressive-image
src="example-image-1x.jpg"
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" />
</progressive-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.

Attributes

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; }

Examples

Browser support

Browsers without native custom element support require a polyfill.