# Image

- Page: https://jiguang132.com/resources/ant-design/docs/image
- Resource: Ant Design (https://jiguang132.com/resources/ant-design.md)
- All guides: https://jiguang132.com/resources/ant-design/docs.md

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 · `basic`
- Progressive Loading · `placeholder`
- Fault tolerant · `fallback`
- Multiple image preview · `preview-group`
- Preview from one image · `preview-group-visible`
- Custom preview image · `previewSrc`
- Controlled Preview · `controlled-preview`
- Custom toolbar render · `toolbarRender`
- Custom preview render · `imageRender`
- preview mask · `mask`
- Custom semantic dom styling · `style-class`


- nested · `nested`




## API

Common props ref：[Common props](#jguang-common-props)

### Image

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

Other Property ref [&lt;img>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#Attributes)

### 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) | - |  |

### 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) | - | 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](#transformtype), image: [ImgInfo](#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](#semantic-dom), 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 | (open: boolean) => void | - |  |
| onTransform | Callback for preview transform changes | { transform: [TransformType](#transformtype), action: [TransformAction](#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](#semantic-dom), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), 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](#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](#transformtype), image: [ImgInfo](#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](#semantic-dom), 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 | (open: boolean, info: { current: number }) => void | - |  |
| onChange | Callback when changing preview image | (current: number, prevCurrent: number) => void | - |  |
| onTransform | Callback for preview transform changes | { transform: [TransformType](#transformtype), action: [TransformAction](#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'
  | 'reset';
```

### 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;
  total: 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

| Semantic node | Native description | Version |
| --- | --- | --- |
| `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 | — |
| `popup.close` | Preview close button element, sets basic button styles | 6.4.0 |

Semantic description source: `vendor/components/image/demo/_semantic.tsx`

## Design Token

Types, inheritance and declarations retain the pinned native source. Defaults are computed by the native theme and may be overridden by ConfigProvider; this table does not invent static defaults.

| Token | Type | Native description |
| --- | --- | --- |
| `zIndexPopup` | `number` | z-index of preview popup |
| `previewOperationSize` | `number` | Size of preview operation icon |
| `previewOperationColor` | `string` | Color of preview operation icon |
| `previewOperationHoverColor` | `string` | Color of hovered preview operation icon |
| `previewOperationColorDisabled` | `string` | Disabled color of preview operation icon |
| `progressAnimationDuration` | `string` | Base duration of loading animation |

Declaration source: `vendor/components/image/style/index.ts`

```ts
import type { CSSObject } from '@ant-design/cssinjs';

import { unit } from '@ant-design/cssinjs';

import { FastColor } from '@ant-design/fast-color';

import type { FullToken, GenerateStyle, GetDefaultToken } from '../../theme/internal';

import { genStyleHooks, mergeToken } from '../../theme/internal';

import { genFocusOutline, genFocusStyle } from '../../style';

import { inkFlow1, inkFlow2, inkFlow3, progressActive } from './progressAnimation';

export interface ComponentToken {
  /**
   * @desc 预览浮层 z-index
   * @descEN z-index of preview popup
   */
  zIndexPopup: number;
  /**
   * @desc 预览操作图标大小
   * @descEN Size of preview operation icon
   */
  previewOperationSize: number;
  /**
   * @desc 预览操作图标颜色
   * @descEN Color of preview operation icon
   */
  previewOperationColor: string;
  /**
   * @desc 预览操作图标悬浮颜色
   * @descEN Color of hovered preview operation icon
   */
  previewOperationHoverColor: string;
  /**
   * @desc 预览操作图标禁用颜色
   * @descEN Disabled color of preview operation icon
   */
  previewOperationColorDisabled: string;
  /**
   * @desc 加载动画基础时长
   * @descEN Base duration of loading animation
   */
  progressAnimationDuration: string;
}

/**
 * @desc Image 组件的 Token
 * @descEN Token for Image component
 */
export interface ImageToken extends FullToken<'Image'> {
  /**
   * @desc 预览类名
   * @descEN Preview class name
   */
  previewCls: string;
  /**
   * @desc 预览切换按钮尺寸
   * @descEN Size of preview switch button
   */
  imagePreviewSwitchSize: number;
}

export type PositionType = 'static' | 'relative' | 'fixed' | 'absolute' | 'sticky' | undefined;
```


## Shared native props {#jguang-common-props}


> Tips: The following generic properties apply to most antd components; those not supported are described separately.

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| style | The additional style | CSSProperties | - |
| className | The additional css class | string | - |
| rootClassName | ClassName on the root element | string | - |
| autoFocus | Auto focus when component mounted, only effective for focusable elements like forms, links, etc. | boolean | false |


## Install and reproduce an example

```bash
npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23
```

Use ConfigProvider and native App; configure dayjs locale separately. Each example lists its complete source files and additional pinned dependencies in View code. Example names select demos, not universal component props. See the resource setup guide for theme, locale and SSR.

## Native type references

The source viewer includes unchanged native implementations and the following source declarations. Inherited types remain in their native packages. English source comments are preserved as code reference.

- `vendor/components/image/PreviewGroup.tsx`
- `vendor/components/image/Progress.tsx`
- `vendor/components/image/index.tsx`
- `vendor/components/image/style/index.ts`

## Source and license

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

Original bilingual prose and executable examples are retained. Website-only embeds and token tables are expanded locally. Ant Design is MIT; separately listed dependency notices also apply. Upload previews block outbound requests and do not provide a backend.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt