https://github.com/andreruffert/progressive-image-element
⚡️ Progressively enhance image placeholders once they are in the viewport
https://github.com/andreruffert/progressive-image-element
custom-element lazy-loading placeholder-image progressive-image web-component
Last synced: 6 months ago
JSON representation
⚡️ Progressively enhance image placeholders once they are in the viewport
- Host: GitHub
- URL: https://github.com/andreruffert/progressive-image-element
- Owner: andreruffert
- License: mit
- Created: 2020-01-30T19:25:55.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2025-05-09T09:08:37.000Z (6 months ago)
- Last Synced: 2025-05-16T02:09:47.434Z (6 months ago)
- Topics: custom-element, lazy-loading, placeholder-image, progressive-image, web-component
- Language: HTML
- Homepage: https://andreruffert.github.io/progressive-image-element/
- Size: 2.75 MB
- Stars: 267
- Watchers: 4
- Forks: 15
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-web-components - `<progressive-image>` - Custom element to progressively enhance image placeholders. (Real World / Components)
README
# <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)
* **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
```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
```
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)