LazyLoadImage

An image that renders only when it comes near the viewport.

import { LazyLoadImage } from "lazymage";

<LazyLoadImage
  alt="A lake at sunset"
  height={480}
  src="/lake.jpg"
  width={640}
/>;

LazyLoadImage accepts all the props of <img>, like src, alt, srcSet, sizes, fetchPriority, and ref. It gives them to the <img> element. decoding is "async" by default.

Props

Prop	Type	Default	Description
`threshold`	`number`	`100`	Distance in px from the viewport at which the image renders.
`visibleByDefault`	`boolean`	`false`	Render the image at once, without a placeholder or an effect.
`placeholder`	`ReactNode`	—	Content to show until the image renders.
`placeholderSrc`	`string`	—	Image to show as the wrapper background until the image loads.
`effect`	`string`	—	Effect class name, like `blur`. Import the CSS file of the effect.
`wrapperClassName`	`string`	—	Class name of the wrapper `<span>`.
`wrapperProps`	`ComponentProps<"span">`	—	Props of the wrapper `<span>`. They override the default wrapper props.
`beforeLoad`	`() => void`	—	Called one time, right before the image renders.
`onLoad`	`(event) => void`	—	Called when the `<img>` loads.
`afterLoad`	`() => void`	—	Deprecated. Use `onLoad`.
`useIntersectionObserver`	`boolean`	`true`	Use an `IntersectionObserver` when the browser supports it.
`scrollPosition`	`ScrollPosition \| null`	—	Scroll position from `trackWindowScroll`.
`delayMethod`	`"throttle" \| "debounce"`	`"throttle"`	How to limit the scroll and resize checks without `IntersectionObserver`.
`delayTime`	`number`	`300`	Time in ms for `delayMethod`.

New props

These props are not in react-lazy-load-image-component.

Prop	Type	Default	Description
`fallbackSrc`	`string`	—	Image to show one time, when `src` fails to load.
`onReady`	`(image: HTMLImageElement) => void`	—	Called when the image is loaded and decoded.
`preload`	`boolean`	`false`	Fetch the image early with the `react-dom` `preload()` function.
`root`	`Element \| Document \| null`	`null`	Scroll container for the `IntersectionObserver`. `null` is the viewport.
`scrollMargin`	`number \| string`	—	Margin for nested scroll containers, in px or as a CSS length. The browser must support it.

The wrapper

lazymage puts the image in a wrapper <span> when one of these conditions is true:

You set effect or placeholderSrc, and visibleByDefault is false.
You set wrapperClassName or wrapperProps.

The wrapper has the lazy-load-image-background class and the effect class. When the image is loaded, it also gets the lazy-load-image-loaded class. The wrapper uses display: inline-block and the width and height of the image.

Load states

The <img> and the wrapper have a data-state attribute.

Value	Meaning
`idle`	The image is not near the viewport yet. Only the wrapper has this value.
`loading`	The image renders and loads.
`loaded`	The image is loaded and decoded.
`error`	The image failed to load. If you set `fallbackSrc`, the fallback also failed.

A new src resets the state to loading. Then the effect plays again, and onLoad is called again.

See Styling for examples.

Callbacks

beforeLoad runs one time, right before the <img> renders.
onLoad and afterLoad run when the <img> sends its load event.
onReady runs after the image is loaded and decoded. It also runs for an image that loaded before React hydrated it.