andreruffert/progressive-image-element

⚡️ <progressive-image> custom element

<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

Install

$ npm install progressive-image-element

Usage

1. 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>

or

// 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"
>
  <!-- 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

• Example page
• Simple fadeIn transition - CodePen
• Save data option with loading state - CodePen
• React Component - CodePen

Browser support

Browsers without native custom element support require a polyfill.

License

MIT © André Ruffert

progressive-image-element's Issues

[Question] Client Hints

It is possible to enable Client Hints in Chrome, to get information about the current connection. Does this have any effect on the savedata option?