# Image - Page: https://jiguang132.com/resources/arco-design/docs/image - Resource: Arco Design (https://jiguang132.com/resources/arco-design.md) - All guides: https://jiguang132.com/resources/arco-design/docs.md Show and preview pictures. ## Install ```bash npm install @arco-design/web-react@2.66.18 ``` Import `@arco-design/web-react/dist/css/arco.css` at the entry and set the locale with `ConfigProvider`. React 19 projects must also import `@arco-design/web-react/es/_util/react-19-adapter` first, or imperative APIs such as Message and Modal cannot render. ## Examples - **Basic**: When you need to view a picture, simply set the `src` property to get a component with picture preview function. - **Show caption**: By setting `title` and `description`, the title and description of the picture can be displayed inside or at the bottom of the picture. The display position is controlled by `footerPosition`. - **Extra operations**: The extra operations are set by `actions` and arranged horizontally by default. If you have more operation buttons, we also provide the `simple` mode to put the buttons in a drop-down box. Note that in the `simple` mode, the description will be unable to display. - **Error state**: Content displayed when the image fails to load. - **Loading**: There is no loading effect by default. Default loading effect can be enabled with `loader=true`. If the default loading effect does not meet the requirements, you can also set the loading style through `loaderClassName`. Loading - **Progressive Loading**: When you need to display a large image, you can pass a smaller image to `loader` to display it when the original image is not successfully loaded to simulate progressive loading. - **Preview control bar**: The function buttons on the control preview control bar can be sorted and filtered through `actionLayout`. Among them, `extra` represents the buttons in `actions`, and the `key` in `actions` also supports separate sorting. - **Multi-image preview**: Use `` to wrap the `` component to preview multiple images. - **Use Preview alone**: `Image.Preview` can be used alone, you need to set `src` and control `visible`. - **Use PreviewGroup alone**: `Image.PreviewGroup` can be used alone, with `visible` and `onVisibleChange` to control its visibility. The image display is divided into two scenes. One is to specify the first image to be displayed by `defaultCurrent`. The other one is to control which image is currently displayed by `current` and `onChange`. - **Popup container**: Use `getPopupContainer` to specify the parent node where the preview should mount to. - **lazyload**: Set `slazyload` to enable lazy loading, and the image will only be loaded when it appears in the viewport The `lazyload` attribute is implemented based on **[IntersectionObserver API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)** Examples come from the official Arco Design repository (MIT) at the commit published as npm 2.66.18. Some use online images or upload endpoints; network requests are disabled in previews. ## API
### Image |Property|Description|Type|DefaultValue|Version| |---|---|---|---|---| |preview|Whether to enable preview|boolean |`true`|-| |simple|Whether to enable simple mode|boolean |`-`|-| |index|Use `Image.PreviewGroup` to wrap the preview index. Generally, you don't need to specify it. When there is a problem with the preview order of multiple images, you can manually specify the preview order of the current `image`|number |`-`|2.23.0| |description|Image description|string |`-`|-| |src|Image path|string |`-`|-| |title|Image title|string |`-`|-| |footerPosition|The position of footer|'inner' \| 'outer' |`inner`|-| |error|Content displayed in error state|ReactNode |`-`|-| |loader|Load transition effect, set `true` to show the default loading effect|boolean \| ReactNode |`-`|-| |actions|Extra operations|ReactNode[] |`-`|-| |className|Additional css class|string \| string[] |`-`|-| |height|Image height|string \| number |`-`|-| |lazyload|lazyload loading [Intersection_Observer](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)|boolean \| IntersectionObserverInit |`-`|2.47.0| |loaderClassName|The style of the loader, will override the default transition effect|string \| string[] |`-`|-| |onError|Triggered when image loading fails|(ev: SyntheticEvent<HTMLImageElement>) => void |`-`|-| |onLoad|Triggered when the image is loaded|(ev: SyntheticEvent<HTMLImageElement>) => void |`-`|-| |previewProps|Preview options (all options are optional) [ImagePreviewProps](#imagepreview)|PartialImagePreviewProps |`-`|-| |style|Additional style|CSSProperties |`-`|-| |width|Image width|string \| number |`-`|-| ### Image.Preview |Property|Description|Type|DefaultValue|Version| |---|---|---|---|---| |closable|Whether display close button|boolean |`true`|2.16.0| |defaultVisible|Whether visible by default|boolean |`-`|-| |escToExit|Whether to enable pressing `ESC` to close the preview.|boolean |`true`|2.24.0| |maskClosable|Whether click mask to close|boolean |`true`|-| |resetTranslate|Enable position correction|boolean |`true`|2.61.0| |visible|Whether is visible|boolean |`-`|-| |breakPoint|The width that triggers the toolbar to switch to simple mode|number |`316`|-| |src|Image path, The default in Image is the src of Image|string **(Required)**|`-`|-| |imgAttributes|Image props, passthrough to the `img` tag in the preview modal|Omit<ImgHTMLAttributes<HTMLImageElement>, 'src'> |`-`|2.39.0| |extra|Additional nodes add to the image preview area|ReactNode |`-`|2.53.0| |actions|Extra operations, [ImagePreviewActionProps](#imagepreviewactionprops)|[ImagePreviewActionProps](image#imagepreviewactionprops)[] |`-`|-| |actionsLayout|The layout of the control bar|string[] |`['fullScreen', 'rotateRight', 'rotateLeft', 'zoomIn', 'zoomOut', 'originalSize', 'extra']`|-| |className|Additional css class|string \| string[] |`-`|-| |scales|The zoom percentage in the current array is used when previewing zooms. If `100%` is not included, the `100%` scale will be automatically added in the most adjacent position.|number[] |`[25, 33, 50, 67, 75, 80, 90, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500];`|2.30.0| |style|Additional style|CSSProperties |`-`|-| |getPopupContainer|Get popup's parent node|() => HTMLElement |`() => document.body`|2.16.0| |imageRender|Rendering of custom IMG elements|(originalNode: ReactElement) => ReactNode |`-`|2.58.0| |onVisibleChange|Callback when visibility changes|(visible: boolean, preVisible: boolean) => void |`-`|-| ### Image.PreviewGroup Start from `v2.14.0` |Property|Description|Type|DefaultValue|Version| |---|---|---|---|---| |closable|Whether display close button|boolean |`true`|2.16.0| |defaultVisible|Whether visible by default|boolean |`-`|-| |escToExit|Whether to enable pressing `ESC` to close the preview.|boolean |`true`|2.24.0| |forceRender|Whether to render the image list for loading images in advance|boolean |`-`|2.58.0| |infinite|Whether to loop infinitely|boolean |`-`|-| |maskClosable|Whether click mask to close|boolean |`true`|-| |resetTranslate|Enable position correction|boolean |`true`|2.61.0| |visible|Whether is visible|boolean |`-`|-| |breakPoint|The width that triggers the toolbar to switch to simple mode|number |`316`|-| |current|The index of current image (controlled prop)|number |`-`|-| |defaultCurrent|The default index of first image|number |`-`|-| |imgAttributes|Image props, passthrough to the `img` tag in the preview modal|Omit<ImgHTMLAttributes<HTMLImageElement>, 'src'> |`-`|2.39.0| |extra|Additional nodes add to the image preview area|ReactNode |`-`|2.53.0| |actions|Extra operations, [ImagePreviewActionProps](#imagepreviewactionprops)|[ImagePreviewActionProps](image#imagepreviewactionprops)[] |`-`|-| |actionsLayout|The layout of the control bar|string[] |`['fullScreen', 'rotateRight', 'rotateLeft', 'zoomIn', 'zoomOut', 'originalSize', 'extra']`|-| |className|Additional css class|string \| string[] |`-`|-| |scales|The zoom percentage in the current array is used when previewing zooms. If `100%` is not included, the `100%` scale will be automatically added in the most adjacent position.|number[] |`[25, 33, 50, 67, 75, 80, 90, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500];`|2.30.0| |srcList|Image path list（After setting this property, the information of the `Image` sub-component will no longer be collected)|string[] |`-`|-| |style|Additional style|CSSProperties |`-`|-| |getPopupContainer|Get popup's parent node|() => HTMLElement |`() => document.body`|2.16.0| |imageRender|Rendering of custom IMG elements|(originalNode: ReactElement) => ReactNode |`-`|2.58.0| |onChange|Callback when image switches|(index: number) => void |`-`|-| |onVisibleChange|Callback when visibility changes|(visible: boolean, preVisible: boolean) => void |`-`|-| ### ImagePreviewActionProps Detailed parameters of type `ImagePreviewActionProps` in ``. |Property|Description|Type|DefaultValue| |---|---|---|---| |disabled|Whether disabled|boolean |`-`| |key|Unique identifier|string **(Required)**|`-`| |name|name|string |`-`| |content|content|ReactNode **(Required)**|`-`| |className|Additional css class|string \| string[] |`-`| |style|Additional style|CSSProperties |`-`| |getContainer|Because content can only specify content, this function is provided to support custom peripheral elements.Note that if `getContainer` is set, the `Tooltip` displaying `name` will be invalid|(actionElement: ReactNode) => ReactNode |`-`|
--- Index of all JGuang resources: https://jiguang132.com/llms.txt