Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/andreruffert/progressive-image-element
⚡️ <progressive-image> custom element
https://github.com/andreruffert/progressive-image-element
custom-element lazy-loading placeholder-image progressive-image web-component
Last synced: 5 days ago
JSON representation
⚡️ <progressive-image> custom element
- Host: GitHub
- URL: https://github.com/andreruffert/progressive-image-element
- Owner: andreruffert
- License: mit
- Created: 2020-01-30T19:25:55.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-01-17T06:45:21.000Z (11 months ago)
- Last Synced: 2024-12-08T03:42:10.067Z (14 days ago)
- Topics: custom-element, lazy-loading, placeholder-image, progressive-image, web-component
- Language: JavaScript
- Homepage: https://andreruffert.github.io/progressive-image-element/examples/
- Size: 2.84 MB
- Stars: 264
- Watchers: 4
- Forks: 14
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- 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
> A progressive image element
[](https://github.com/andreruffert/progressive-image-element/actions?workflow=CI)
[](https://www.npmjs.com/package/progressive-image-element)
[](https://www.npmjs.com/package/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
```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; }
```
## Examples
- [Example page](https://andreruffert.github.io/progressive-image-element/examples)
- [Simple fadeIn transition - CodePen](https://codepen.io/andreruffert/full/mdyZLrQ)
- [Save data option with loading state - CodePen](https://codepen.io/andreruffert/full/yLydrdb)
- [React Component - CodePen](https://codepen.io/andreruffert/full/KKpKVRO)
## Browser support
Browsers without native [custom element support][support] require a [polyfill][].
[support]: https://caniuse.com/#feat=custom-elementsv1
[polyfill]: https://github.com/webcomponents/polyfills/tree/master/packages/custom-elements
## License
MIT © [André Ruffert](https://andreruffert.com)