Image

Preview-able image.

When to use

When you need to display pictures.
Display when loading a large image or fault tolerant handling when loading fail.

Examples

Basic Usage

Click the image to zoom in.

Fault tolerant

Load failed to display image placeholder.

Preview from one image

Preview a collection from one image.

Controlled Preview

You can make preview controlled.

Custom preview render

You can customize the preview content.

Custom semantic dom styling

You can customize the semantic dom style of Image by passing objects/functions through classNames and styles.

Progressive Loading

Set placeholder via placeholder prop. When placeholder is { progress: true }, it shows a watercolor ink loading animation; when set to { progress: { percent: number } }, it shows a progress bar; you can also pass a custom React node as placeholder.

Multiple image preview

Click the left and right switch buttons to preview multiple images.

Custom preview image

You can set different preview image.

Custom toolbar render

You can customize the toolbar and add a button for downloading the original image or downloading the flipped and rotated image.

preview mask

mask effect.

nested

Nested in the modal

API

Image and Image.PreviewGroup are exported from @ceebee/ui/client.

Preview control names use LabelsProvider keys, including imagePrevious, imageNext, and the image transform labels. Ant Design continues to own preview navigation, zoom, focus, keyboard, and dismissal behavior.

The full-screen preview uses a solid dark canvas so its light toolbar controls stay readable over any image.

Image

Property	Description	Type	Default	Version
`alt`	Image description	`string`	`-`	—
`classNames`	Customize class for each semantic structure inside the component. Supports object or function.	`Record<SemanticDOM, string> \| (info: { props })=> Record<SemanticDOM, string>`	`-`	—
`fallback`	Fallback URL when load fails	`string`	`-`	—
`height`	Image height	`string \| number`	`-`	—
`placeholder`	Loading placeholder, supports ReactNode or config object	`PlaceholderType`	`-`	—
`preview`	Preview configuration; set to false to disable	`boolean \| PreviewType`	`true`	—
`src`	Image URL	`string`	`-`	—
`styles`	Customize inline style for each semantic structure inside the component. Supports object or function.	`Record<SemanticDOM, CSSProperties> \| (info: { props })=> Record<SemanticDOM, CSSProperties>`	`-`	—
`width`	Image width	`string \| number`	`-`	—
`onError`	Callback when loading error occurs	`(event: Event) => void`	`-`	—

PlaceholderType

Property	Description	Type	Default	Version
`progress`	Progress config, set to true to show gradient animation, set { percent: number } to show progress, render for custom rendering	`boolean \| ImageProgressConfig`	`-`	—

ImageProgressConfig

Property	Description	Type	Default	Version
`percent`	Progress value	`number`	`-`	—
`render`	Custom rendering, receives default progress UI and percentage	`(progress: React.ReactNode, percent: number) => React.ReactNode`	`-`	—

PreviewType

Property	Description	Type	Default	Version
`actionsRender`	Custom toolbar render	`(originalNode: React.ReactElement, info: ToolbarRenderInfoType) => React.ReactNode`	`-`	—
`closeIcon`	Custom close icon	`React.ReactNode`	`-`	—
`cover`	Custom preview mask	`React.ReactNode \| CoverConfig`	`-`	CoverConfig support after v6.0
`focusTrap`	Whether to trap focus within the preview when open	`boolean`	`true`	6.4.0
`destroyOnClose`	Destroy child elements on preview close (removed, no longer supported)	`boolean`	`false`	—
`forceRender`	Force render preview image (removed, no longer supported)	`boolean`	`-`	—
`getContainer`	Specify container for preview mounting; still full screen; false mounts at current location	`string \| HTMLElement \| (() => HTMLElement) \| false`	`-`	—
`imageRender`	Custom preview content	`(originalNode: React.ReactElement, info: { transform: TransformType, image: ImgInfo }) => React.ReactNode`	`-`	—
`mask`	preview mask effect	`boolean \| { enabled?: boolean, blur?: boolean, closable?: boolean }`	`true`	mask.closable: 6.4.0
`maskClassName`	Thumbnail mask class name; please use 'classNames.cover' instead	`string`	`-`	—
`maxScale`	Maximum zoom scale	`number`	`50`	—
`minScale`	Minimum zoom scale	`number`	`1`	—
`movable`	Whether the preview image can be dragged when it is larger than the viewport	`boolean`	`true`	—
`open`	Whether to display preview	`boolean`	`-`	—
`rootClassName`	Root DOM class name for preview; applies to both image and preview wrapper	`string`	`-`	—
`scaleStep`	Each step's zoom multiplier is 1 + scaleStep	`number`	`0.5`	—
`src`	Custom preview src	`string`	`-`	—
`styles`	Custom semantic structure styles	`Record<SemanticDOM, CSSProperties>`	`-`	—
`wheel`	Whether to enable mouse wheel zoom	`boolean`	`true`	6.6.0
`toolbarRender`	Custom toolbar; please use 'actionsRender' instead	`(originalNode: React.ReactElement, info: Omit<ToolbarRenderInfoType, 'current' \| 'total'>) => React.ReactNode`	`-`	—
`visible`	Whether to show; please use 'open' instead	`boolean`	`-`	—
`onOpenChange`	Callback when preview open state changes	`(visible: boolean) => void`	`-`	—
`onTransform`	Callback for preview transform changes	`{ transform: TransformType, action: TransformAction }`	`-`	—
`onVisibleChange`	Callback when 'visible' changes; please use 'onOpenChange' instead	`(visible: boolean, prevVisible: boolean) => void`	`-`	—

PreviewGroup

Property	Description	Type	Default	Version
`classNames`	Customize class for each semantic structure inside the component. Supports object or function.	`Record<SemanticDOM, string> \| (info: { props })=> Record<SemanticDOM, string>`	`-`	—
`fallback`	Fallback URL for load error	`string`	`-`	—
`items`	Array of preview items	`string[] \| { src: string, crossOrigin: string, ... }[]`	`-`	—
`preview`	Preview configuration; disable by setting to false	`boolean \| PreviewGroupType`	`true`	—

PreviewGroupType

Property	Description	Type	Default	Version
`actionsRender`	Custom toolbar render	`(originalNode: React.ReactElement, info: ToolbarRenderInfoType) => React.ReactNode`	`-`	—
`closeIcon`	Custom close icon	`React.ReactNode`	`-`	—
`countRender`	Custom preview count render	`(current: number, total: number) => React.ReactNode`	`-`	—
`focusTrap`	Whether to trap focus within the preview when open	`boolean`	`true`	6.4.0
`current`	Index of the current preview image	`number`	`-`	—
`forceRender`	Force render preview image (removed, no longer supported)	`boolean`	`-`	—
`getContainer`	Specify container for preview mounting; still full screen; false mounts at current location	`string \| HTMLElement \| (() => HTMLElement) \| false`	`-`	—
`imageRender`	Custom preview content	`(originalNode: React.ReactElement, info: { transform: TransformType, image: ImgInfo, current: number }) => React.ReactNode`	`-`	—
`mask`	preview mask effect	`boolean \| { enabled?: boolean, blur?: boolean, closable?: boolean }`	`true`	mask.closable: 6.4.0
`maskClassName`	Thumbnail mask class name; please use 'classNames.cover' instead	`string`	`-`	—
`minScale`	Minimum zoom scale	`number`	`1`	—
`maxScale`	Maximum zoom scale	`number`	`50`	—
`movable`	Whether the preview image can be dragged when it is larger than the viewport	`boolean`	`true`	—
`open`	Whether to display preview	`boolean`	`-`	—
`rootClassName`	Root DOM class name for preview; applies to both image and preview wrapper. Use 'classNames.root' instead	`string`	`-`	—
`styles`	Custom semantic structure styles	`Record<SemanticDOM, CSSProperties>`	`-`	—
`wheel`	Whether to enable mouse wheel zoom	`boolean`	`true`	6.6.0
`scaleStep`	Each step's zoom multiplier is 1 + scaleStep	`number`	`0.5`	—
`toolbarRender`	Custom toolbar; please use 'actionsRender' instead	`(originalNode: React.ReactElement, info: ToolbarRenderInfoType) => React.ReactNode`	`-`	—
`visible`	Whether to show; please use 'open' instead	`boolean`	`-`	—
`onOpenChange`	Callback when preview open state changes, includes current preview index	`(visible: boolean, info: { current: number }) => void`	`-`	—
`onChange`	Callback when changing preview image	`(current: number, prevCurrent: number) => void`	`-`	—
`onTransform`	Callback for preview transform changes	`{ transform: TransformType, action: TransformAction }`	`-`	—
`onVisibleChange`	Callback when 'visible' changes; please use 'onOpenChange' instead	`(visible: boolean, prevVisible: boolean, current: number) => void`	`-`	—