# <progressive-image> element > Progressively enhance image placeholders once they are in the viewport. [![Test](https://img.shields.io/github/actions/workflow/status/andreruffert/syntax-highlight-element/test.yml?label=Test&logo=github&color=ffc300&labelColor=212121)](https://github.com/andreruffert/progressive-image-element/actions/workflows/test.yml) [![npm version](https://img.shields.io/npm/v/progressive-image-element.svg?color=ffc300&labelColor=212121)](https://www.npmjs.com/package/progressive-image-element) [![npm downloads](https://img.shields.io/npm/dm/progressive-image-element?logo=npm&color=ffc300&labelColor=212121)](https://www.npmjs.com/package/progressive-image-element) [![jsDelivr hits (npm)](https://img.shields.io/jsdelivr/npm/hm/progressive-image-element?color=ffc300&labelColor=212121)](https://www.jsdelivr.com/package/npm/progressive-image-element) * **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
progressive image element markup example
## Install ```console $ npm install progressive-image-element ``` ## Usage 1. Include the script & stylesheet within your application ```html ``` or ```js // Import the custom element script import ProgressiveImageElement from 'progressive-image-element'; ``` 2. Use the `` element markup ```html Image ``` The placeholder image should be a solid color placeholder, [LQIP](http://www.guypo.com/introducing-lqip-low-quality-image-placeholders) or [SQIP](https://github.com/technopagan/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](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/srcset) - `sizes` Comma-separated list of [source size descriptors](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes) - `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 `` when the image is ready to load on user interaction (`click`). Used for slow connections or when the `savedata` attribute is present. ```css progressive-image.loadable { ... } ``` A CSS class `[loading]` is present on `` while the image is loading. ```css progressive-image.loading { ... } ``` A CSS class `.loaded` is present on `` children of `` when the image was loaded. ```css progressive-image > img { opacity: 0; } progressive-image > img.loaded { opacity: 1; } ``` ## License Distributed under the MIT license. See LICENSE for details. © [André Ruffert](https://andreruffert.com)