https://github.com/willybrauner/lazy-image
💤 A zero dependency lazy and responsive image management for image and background-image
https://github.com/willybrauner/lazy-image
background-image image lazyload lib library react typescript
Last synced: about 1 year ago
JSON representation
💤 A zero dependency lazy and responsive image management for image and background-image
- Host: GitHub
- URL: https://github.com/willybrauner/lazy-image
- Owner: willybrauner
- Created: 2021-08-18T08:16:21.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2022-12-13T11:28:51.000Z (over 3 years ago)
- Last Synced: 2025-03-24T16:47:25.249Z (over 1 year ago)
- Topics: background-image, image, lazyload, lib, library, react, typescript
- Language: TypeScript
- Homepage:
- Size: 657 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# @wbe/lazy-image
A zero dependency lazy and responsive image management for image and background-image.
React wrapper component using `lazy-image` is available too.
Because the native `loading="lazy"` is not supported on all browsers for now, this library used intersection-observer to detect when the image is visible in the viewport.
## Summary
- [Vanilla LazyImage](#LazyImage)
- [React LazyImage](#ReactLazyImage)
## Installation
```shell script
$ npm install -s @wbe/lazy-image
```
### Lazyload a group of images
Lazy image is build to manage lazyloading and responsive via native srcset.
HTML template:
```html
![image]()
![image-2]()
```
```js
import { LazyImage } from "@wbe/lazy-image"
const image = new LazyImage()
// start to listen
image.start()
// stop to listen
image.stop()
// update listeners
image.update()
```
When image is appear in viewport, data-srcset value is injected in srcset attribute.
```html
![image]()
```
### Lazyload a specific image
`LazyImage()` can lazyload specific image only.
```html
![image]()
```
```js
const singleImage = new LazyImage({
$element: document.getElementById("singleImage"),
})
```
### Parameters
All parameters are optional.
| param | type | description | default value |
| ----------------- | -------------------------- | ----------------------------------------------------------------------------------- | --------------- |
| `$root` | `string` | parent DOM element who contains images to lazyload | `document.body` |
| `$element` | `HTMLElement` | lazyLoad a specific DOM image element | / |
| `src` | `string` | if $element is set, define an image src to lazyload | / |
| `srcset` | `string` | if $element is set, define an image srcset to lazyload | / |
| `lazyCallback` | `(state)=> void` | callback executed when lazy state change (`lazyload`, `lazyloading` , `lazyloaded`) | `() => {}` |
| `observerOptions` | `IntersectionObserverInit` | mutation observer options | `{}` |
## LazyBackgroundImage
`LazyBackgroundImage()` set the appropriate image URL from srcset, in CSS background-image url of specific div.
This appropriate image URL depends of element width.
### Lazyload a group of background-images
```html
```
```js
import { LazyBackgroundImage } from "@wbe/lazy-image"
const backgroundImage = new LazyBackgroundImage()
backgroundImage.start()
```
When DOM element appear in viewport, and element width is less than 360px:
```html
```
### Lazyload a specific background-image
`LazyBackgroundImage()` can lazyload specific css image only.
```html
```
```js
import { LazyBackgroundImage } from "@wbe/lazy-image"
const singleBackgroundImage = new LazyBackgroundImage({
$element: document.getElementById("single"),
})
// start to listen
singleBackgroundImage.start()
// stop to listen
singleBackgroundImage.stop()
// update listeners
singleBackgroundImage.update()
```
Or don't specify image srcset in DOM but, directly as function param.
```html
```
```js
import { LazyBackgroundImage } from "@wbe/lazy-image"
const singleBackgroundImage = LazyBackgroundImage({
$element: document.getElementById("single"),
srcset: "img-1.jpg 360w, img-2.jpg 768w",
})
singleBackgroundImage.start()
```
## Parameters
All parameters are optional.
| param | type | description | default value |
| ----------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `$root` | `string` | parent DOM element who contains images to lazyload | `document.body` |
| `$element` | `HTMLElement` | lazyLoad a specific DOM image element | / |
| `srcset` | `string` | if $element is set, define an image srcset to lazyload | / |
| `additonalUrl` | `string` | add a second css URL behind the first one | / |
| `lazyCallback` | `(state)=> void` | callback executed when lazy state change (`lazyload`, `lazyloading` , `lazyloaded`) | `() => {}` |
| `observerOptions` | `IntersectionObserverInit` | mutation observer options | / |
| `bigQuality` | `boolean` | will returns 2 steps bigger image (ex: if 360, 768, 1024 img are available, and DOM element width is less than 360, the function will return 768 img instead the 360 ) | `false` |
React image component with lazyloading management.
## `` component
```js
import { Image } from "@wbe/lazy-image"
```
### `src` props
Be sure you set appropriated css image width and height.
```js
```
Will return this HTML before lazyload:
```html
```
and after lazyload:
```html
```
### `srcset` props
```js
```
### `data` props
Will generate an appropriated srcset string.
```js
const data = [
{
url: "https://url",
width: 600,
height: 400,
},
{
url: "https://url-2",
width: 1000,
height: 800,
},
]
;
```
### `srcPlaceholder` props
Allow to display specific low quality image before lazyloading src image.
```js
```
### Props list
```ts
interface IProps {
// image to display before lazyload
// default is lightest base64 transparent image
srcPlaceholder?: string
// src URL to lazyload
src?: string
// srcset URL to lazyload
srcset?: string
// list of images with dimension used to build srcset attr
data?: TImageData[]
// callback when lazyload state change (lazyload | lazyloading | lazyloaded)
lazyCallback?: (lazyState: TLazy) => void
// intersection observer options
observerOptions?: IntersectionObserverInit
// alt attr and aria html
alt: string
ariaLabel?: string
// class name added on root element
className?: string
// style attrs
style?: CSSProperties
width?: number | string
height?: number | string
}
```
## ``
Works this the same API than `` component.
Before lazyload:
```html
```
After lazyload:
```html
```
## `` wrapper component
Image component comes with `` parent component
used to display a placeholder behind Image. This process is particulary useful
when image is lazyloading. It allows to not preload all 1px height images in pages
on page load but really waiting the image was shown in viewport to lazyload it.
Example with ``:
```js
```
Example with ``:
```js
```
`` get children Image ratio to calculate its placeholder height.
It's possible to specify an arbitrary ratio who will override image dimension
```js
```
## Props list
```ts
interface IProps {
// Image component
children: ReactNode
// by default, ratio is calc from children image data dimension.
// set ratio override native image ratio
ratio?: number
// shortcut to style wrapper background color
backgroundColor?: string
// add style to each dom element
style?: {
root?: CSSProperties
wrapper?: CSSProperties
img?: CSSProperties
}
// class name added on root element
className?: string
}
```