Ant Design

⌘ K

6.0.0-alpha.2

Image

Preview-able image.

Importimport { Image } from "antd";

Sourcecomponents/image

Docs

Edit this page Changelog

contributors

Empty List

Ant Design

⌘ K

6.0.0-alpha.2

Image

Preview-able image.

Importimport { Image } from "antd";

Sourcecomponents/image

Docs

Edit this page Changelog

contributors

Empty List

When To Use

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

Examples

API

Common props ref：Common props

Image

Property	Description	Type	Default
alt	Image description	string	-
classNames	Custom semantic structure class names	Record<SemanticDOM, string>	-
fallback	Fallback URL when load fails	string	-
height	Image height	string \| number	-
placeholder	Loading placeholder; if true, uses default placeholder	ReactNode	-
preview	Preview configuration; set to false to disable	boolean \| PreviewType	true
src	Image URL	string	-
styles	Custom semantic structure styles	Record<SemanticDOM, string>	-
width	Image width	string \| number	-
onError	Callback when loading error occurs	(event: Event) => void	-

Other Property ref <img>

PreviewType

Property	Description	Type	Default	Version
actionsRender	Custom toolbar render	(originalNode: React.ReactElement, info: ToolbarRenderInfoType) => React.ReactNode	-
classNames	Custom semantic structure class names	Record<SemanticDOM, string>	-
closeIcon	Custom close icon	React.ReactNode	-
cover	Custom preview mask	React.ReactNode \| CoverConfig	-	CoverConfig support after v6.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~~	Thumbnail mask, please use 'cover' instead	ReactNode	-
~~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 it is movable	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, string>	-
~~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
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
actionsRender	Custom toolbar render	(originalNode: React.ReactElement, info: ToolbarRenderInfoType) => React.ReactNode	-
classNames	Custom preview class names object	Record<SemanticDOM, string>	-
closeIcon	Custom close icon	React.ReactNode	-
countRender	Custom preview count render	(current: number, total: number) => React.ReactNode	-
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~~	Thumbnail mask, please use 'cover' instead	ReactNode	-
~~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 movable	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, string>	-
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	-

Interface

TransformType

typescript

{
  x: number;
  y: number;
  rotate: number;
  scale: number;
  flipX: boolean;
  flipY: boolean;
}

TransformAction

typescript

type TransformAction =
  | 'flipY'
  | 'flipX'
  | 'rotateLeft'
  | 'rotateRight'
  | 'zoomIn'
  | 'zoomOut'
  | 'close'
  | 'prev'
  | 'next'
  | 'wheel'
  | 'doubleClick'
  | 'move'
  | 'dragRebound';

ToolbarRenderInfoType

typescript

{
  icons: {
    flipYIcon: React.ReactNode;
    flipXIcon: React.ReactNode;
    rotateLeftIcon: React.ReactNode;
    rotateRightIcon: React.ReactNode;
    zoomOutIcon: React.ReactNode;
    zoomInIcon: React.ReactNode;
  };
  actions: {
    onActive?: (index: number) => void; // support after 5.21.0
    onFlipY: () => void;
    onFlipX: () => void;
    onRotateLeft: () => void;
    onRotateRight: () => void;
    onZoomOut: () => void;
    onZoomIn: () => void;
    onReset: () => void; // support after 5.17.3
    onClose: () => void;
  };
  transform: TransformType,
  current: number;
  image: ImgInfo
}

ImgInfo

typescript

{
  url: string;
  alt: string;
  width: string | number;
  height: string | number;
}

CoverConfig

typescript

type CoverConfig = {
  coverNode?: React.ReactNode;// The custom node of preview mask
  placement?: 'top' | 'bottom' | 'center'; // Set the position of the preview mask display.
}

Semantic DOM

Design Token

Component TokenHow to use?

Token Name	Description	Type	Default Value
previewOperationColor	Color of preview operation icon	string	rgba(255,255,255,0.65)
previewOperationColorDisabled	Disabled color of preview operation icon	string	rgba(255,255,255,0.25)
previewOperationHoverColor	Color of hovered preview operation icon	string	rgba(255,255,255,0.85)
previewOperationSize	Size of preview operation icon	number	18
zIndexPopup	z-index of preview popup	number	1080

Global TokenHow to use?

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.

Progressive Loading

Progressive when large image loading.

Multiple image preview

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

Preview from one image

Preview a collection from one image.

Custom preview image

You can set different preview image.

Controlled Preview

You can make preview controlled.

Custom toolbar render

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

Custom preview render

You can customize the preview content.

nested

Nested in the modal

API

Common props ref：Common props

Image

Property	Description	Type	Default
alt	Image description	string	-
classNames	Custom semantic structure class names	Record<SemanticDOM, string>	-
fallback	Fallback URL when load fails	string	-
height	Image height	string \| number	-
placeholder	Loading placeholder; if true, uses default placeholder	ReactNode	-
preview	Preview configuration; set to false to disable	boolean \| PreviewType	true
src	Image URL	string	-
styles	Custom semantic structure styles	Record<SemanticDOM, string>	-
width	Image width	string \| number	-
onError	Callback when loading error occurs	(event: Event) => void	-

Other Property ref <img>

PreviewType

Property	Description	Type	Default	Version
actionsRender	Custom toolbar render	(originalNode: React.ReactElement, info: ToolbarRenderInfoType) => React.ReactNode	-
classNames	Custom semantic structure class names	Record<SemanticDOM, string>	-
closeIcon	Custom close icon	React.ReactNode	-
cover	Custom preview mask	React.ReactNode \| CoverConfig	-	CoverConfig support after v6.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~~	Thumbnail mask, please use 'cover' instead	ReactNode	-
~~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 it is movable	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, string>	-
~~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
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
actionsRender	Custom toolbar render	(originalNode: React.ReactElement, info: ToolbarRenderInfoType) => React.ReactNode	-
classNames	Custom preview class names object	Record<SemanticDOM, string>	-
closeIcon	Custom close icon	React.ReactNode	-
countRender	Custom preview count render	(current: number, total: number) => React.ReactNode	-
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~~	Thumbnail mask, please use 'cover' instead	ReactNode	-
~~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 movable	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, string>	-
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	-

Interface

TransformType

typescript

{
  x: number;
  y: number;
  rotate: number;
  scale: number;
  flipX: boolean;
  flipY: boolean;
}

TransformAction

typescript

type TransformAction =
  | 'flipY'
  | 'flipX'
  | 'rotateLeft'
  | 'rotateRight'
  | 'zoomIn'
  | 'zoomOut'
  | 'close'
  | 'prev'
  | 'next'
  | 'wheel'
  | 'doubleClick'
  | 'move'
  | 'dragRebound';

ToolbarRenderInfoType

typescript

{
  icons: {
    flipYIcon: React.ReactNode;
    flipXIcon: React.ReactNode;
    rotateLeftIcon: React.ReactNode;
    rotateRightIcon: React.ReactNode;
    zoomOutIcon: React.ReactNode;
    zoomInIcon: React.ReactNode;
  };
  actions: {
    onActive?: (index: number) => void; // support after 5.21.0
    onFlipY: () => void;
    onFlipX: () => void;
    onRotateLeft: () => void;
    onRotateRight: () => void;
    onZoomOut: () => void;
    onZoomIn: () => void;
    onReset: () => void; // support after 5.17.3
    onClose: () => void;
  };
  transform: TransformType,
  current: number;
  image: ImgInfo
}

ImgInfo

typescript

{
  url: string;
  alt: string;
  width: string | number;
  height: string | number;
}

CoverConfig

typescript

type CoverConfig = {
  coverNode?: React.ReactNode;// The custom node of preview mask
  placement?: 'top' | 'bottom' | 'center'; // Set the position of the preview mask display.
}

Semantic DOM

Design Token

Component TokenHow to use?

Token Name	Description	Type	Default Value
previewOperationColor	Color of preview operation icon	string	rgba(255,255,255,0.65)
previewOperationColorDisabled	Disabled color of preview operation icon	string	rgba(255,255,255,0.25)
previewOperationHoverColor	Color of hovered preview operation icon	string	rgba(255,255,255,0.85)
previewOperationSize	Size of preview operation icon	number	18
zIndexPopup	z-index of preview popup	number	1080

Global TokenHow to use?

Basic Usage

Click the image to zoom in.

Fault tolerant

Load failed to display image placeholder.

Progressive Loading

Progressive when large image loading.

Multiple image preview

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

Preview from one image

Preview a collection from one image.

Custom preview image

You can set different preview image.

Controlled Preview

You can make preview controlled.

Custom toolbar render

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

Custom preview render

You can customize the preview content.

nested

Nested in the modal

scaleStep:

root
Root element, sets relative positioning and inline-block layout styles
image
Image element, sets width, height and vertical alignment styles
cover
Image hover display prompt element, sets absolute positioning, background color, opacity and transition animation styles
popup.root
Preview root element, sets fixed positioning, z-index and background mask styles
popup.mask
Preview mask element, sets absolute positioning and semi-transparent background styles
popup.body
Preview body element, sets flex layout, center alignment and pointer event styles
popup.footer
Preview footer element, sets absolute positioning, center layout and bottom operation area styles
popup.actions
Preview actions group element, sets flex layout, background color, border radius and action button styles

Image

Image

When To Use

Examples

API

Image

PreviewType

PreviewGroup

PreviewGroupType

Interface

TransformType

TransformAction

ToolbarRenderInfoType

ImgInfo

CoverConfig

Semantic DOM

Design Token

When To Use

Examples

API

Image

PreviewType

PreviewGroup

PreviewGroupType

Interface

TransformType

TransformAction

ToolbarRenderInfoType

ImgInfo

CoverConfig

Semantic DOM

Design Token

root

image

cover

popup.root

popup.mask

popup.body

popup.footer

popup.actions