Image

The Image component is used to display images with support for fallback.

Storybook @nextui-org/image Source Styles source

Installation

npx nextui-cli@latest add image

The above command is for individual installation only. You may skip this step if @nextui-org/react is already installed globally.

Import

Usage

Blurred

You can use the isBlurred prop to duplicate the image and blur it to create a blurred effect.

Zoomed

You can use the isZoomed prop make the image zoomed when hovered.

Animated Loading

Image component has a built-in skeleton animation to indicate the image is loading and an opacity animation when the image loads.

Note: The URL uses https://app.requestly.io/delay to simulate a slow network.

Image with fallback

You can use the fallbackSrc prop to display a fallback image when:

The fallbackSrc prop is provided.
The image provided in src is still loading.
The image provided in src fails to load.
The image provided in src is not found.

With Next.js Image

Next.js provides an optimized Image component, you can use it with NextUI Image component as well.

Note: NextUI's Image component is client-side, using hooks like useState for loading states and animations. Use Next.js Image alone if these features aren't required.

Slots

img: Slot for the image element.
wrapper: Image wrapper, it handles alignment, placement, and general appearance.
zoomedWrapper: The wrapper slot for the zoomed image it avoids the image content to overflow the parent container.
blurredImg: The wrapper slot for the duplicated blurred image.

API

Image Props

Attribute	Type	Description	Default
src	`string`	The image source.	-
srcSet	`string`	The image srcSet.	-
sizes	`string`	The image sizes.	-
alt	`string`	The image alt.	-
width	`number`	The image width.	-
height	`number`	The image height.	-
radius	`none` \| `sm` \| `md` \| `lg` \| `full`	The image border radius.	`xl`
shadow	`none` \| `sm` \| `md` \| `lg`	The image shadow.	`none`
loading	`eager` \| `lazy`	A loading strategy to use for the image.	-
fallbackSrc	`string`	The fallback image source.	-
isBlurred	`boolean`	Whether the image should have a duplicated blurred image at the background.	`false`
isZoomed	`boolean`	Whether the image should be zoomed when hovered.	`false`
removeWrapper	`boolean`	Whether to remove the wrapper element. This will cause the image to be rendered as a direct child of the parent element. If you set this prop as `true` neither the skeleton nor the zoom effect will work.	`false`
disableSkeleton	`boolean`	Whether the image should disable the skeleton animation while loading.	`false`
classNames	`Record<"img"｜ "wrapper"｜ "zoomedWrapper"｜ "blurredImg", string>`	Allows to set custom class names for the image slots.	-

Image Events

Attribute	Type	Description
onLoad	`ReactEventHandler<HTMLImageElement>`	Handler that is called when the image load.
onError	`() => void`	Handler that is called when the image fails to load.