<progressive-image>

A simple web component to progressively enhance image placeholders once they are in the viewport.

npm i progressive-image-element

Example

<progressive-image savedata src="https://images.unsplash.com/photo-1433477077279-9354d2d72f6b?auto=format&fit=crop&w=510&h=340&q=80" srcset="https://images.unsplash.com/photo-1433477077279-9354d2d72f6b?auto=format&fit=crop&w=1020&h=680&q=80 2x, https://images.unsplash.com/photo-1433477077279-9354d2d72f6b?auto=format&fit=crop&w=510&h=340&q=80 1x" > <img src="https://images.unsplash.com/photo-1433477077279-9354d2d72f6b?auto=format&fit=crop&w=30&h=20&q=50" width="510" height="340" alt="" /> </progressive-image>

Placeholder image size 30x20

Features

According to Web Almanac, images account for a large portion of the page weight of a typical website and can have a significant impact on your site's LCP performance.

The <progressive-image> element extends the HTML <img> element with features to improve the initial page weight:

Faster page load: Images are loaded only as they enter the viewport, using native browser lazy loading with placeholders
Visual stability: Prevent layout shifts when loading images
Save data option: Load images only on demand
No dependencies: Framework agnostic web component

Install

Install via npm

npm i progressive-image-element

Usage

1. Include the script & stylesheet within your application

<link rel="stylesheet" href="https://unpkg.com/progressive-image-element@latest/dist/progressive-image-element.css" />  <script src="https://unpkg.com/progressive-image-element@latest/dist/index.js"></script>

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

2. Use the <progressive-image> element markup

<progressive-image src="example-image-1x.jpg" srcset="example-image-2x.jpg 2x, example-image-1x.jpg 1x" >  <img src="placeholder-image.jpg" width="300" height="200" alt="Image" /> </progressive-image>

Use a solid color, LQIP, or SQIP image placeholder. This will 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 the <progressive-image> element 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 the <progressive-image> element while the image is loading.

progressive-image.loading { … }

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

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

Examples

For more examples checkout the CodePen <progressive-image> element collection.