progressive-image-element
# <progressive-image> element > Progressively enhance image placeholders once they are in the viewport. [](https://github.com/andreruffert/progressive-image-element/actions/workflows/test.yml) [](https://www.npmjs.com/package/progressive-image-element) [](https://www.npmjs.com/package/progressive-image-element) [](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 <div align="center"> <img src="example-2x.png" alt="progressive image element markup example" width="774"> </div> ## Install ```console $ npm install progressive-image-element ``` ## Usage 1. Include the script & stylesheet within your application ```html <!-- 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 type="module" src="https://unpkg.com/progressive-image-element@latest/dist/progressive-image-element.js"></script> ``` or ```js // Import the custom element script import ProgressiveImageElement from 'progressive-image-element'; ``` 2. Use the `<progressive-image>` element markup ```html <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](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 `<progressive-image>` 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 `<progressive-image>` while the image is loading. ```css progressive-image.loading { ... } ``` A CSS class `.loaded` is present on `<img>` children of `<progressive-image>` 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)