Image
Show and preview pictures.
Install
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
srcproperty to get a component with picture preview function. - Show caption: By setting
titleanddescription, the title and description of the picture can be displayed inside or at the bottom of the picture. The display position is controlled byfooterPosition. - Extra operations: The extra operations are set by
actionsand arranged horizontally by default. If you have more operation buttons, we also provide thesimplemode to put the buttons in a drop-down box. Note that in thesimplemode, 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 throughloaderClassName. Loading - Progressive Loading: When you need to display a large image, you can pass a smaller image to
loaderto 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,extrarepresents the buttons inactions, and thekeyinactionsalso supports separate sorting. - Multi-image preview: Use
<Image.PreviewGroup>to wrap the<Image>component to preview multiple images. - Use Preview alone:
Image.Previewcan be used alone, you need to setsrcand controlvisible. - Use PreviewGroup alone:
Image.PreviewGroupcan be used alone, withvisibleandonVisibleChangeto control its visibility. The image display is divided into two scenes. One is to specify the first image to be displayed bydefaultCurrent. The other one is to control which image is currently displayed bycurrentandonChange. - Popup container: Use
getPopupContainerto specify the parent node where the preview should mount to. - lazyload: Set
slazyloadto enable lazy loading, and the image will only be loaded when it appears in the viewport Thelazyloadattribute is implemented based on IntersectionObserver 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
<div class="image-demo-props">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 | 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 | 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[] | - | - |
| 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[] | - | - |
| 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 <Image.Preview>.
| 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 | - |