Image
Besides the native features of img, support lazy load, custom placeholder and load failure, etc.
Basic Usage Indicate how the image should be resized to fit its container by fit, same as native object-fit .
export function ImageBasic() { return ( <div> <div style={EQUAL_BLOCK_STYLE}> <span style={DEMONSTRATION_STYLE}>fill</span> <ElImage src={URL} fit="fill" style={IMAGE_BOX_STYLE} /> </div> <div style={EQUAL_BLOCK_STYLE}> <span style={DEMONSTRATION_STYLE}>contain</span> <ElImage src={URL} fit="contain" style={IMAGE_BOX_STYLE} /> </div> <div style={EQUAL_BLOCK_STYLE}> <span style={DEMONSTRATION_STYLE}>cover</span> <ElImage src={URL} fit="cover" style={IMAGE_BOX_STYLE} /> </div> <div style={EQUAL_BLOCK_STYLE}> <span style={DEMONSTRATION_STYLE}>none</span> <ElImage src={URL} fit="none" style={IMAGE_BOX_STYLE} /> </div> <div style={EQUAL_BLOCK_STYLE}> <span style={DEMONSTRATION_STYLE}>scale-down</span> <ElImage src={URL} fit="scale-down" style={IMAGE_BOX_STYLE} /> </div> </div> ); } Placeholder Custom placeholder content when image hasn't loaded yet by slot = placeholder
export function ImagePlaceholder() { const src = "https://cube.elemecdn.com/6/94/4d3ea53c084bad6931a56d5158a48jpeg.jpeg"; const slotStyle: CSSProperties = { display: "flex", justifyContent: "center", alignItems: "center", width: "100%", height: "100%", background: "var(--el-fill-color-light)", color: "var(--el-text-color-secondary)", fontSize: 14, }; return ( <div> <div style={{ ...EQUAL_BLOCK_STYLE, width: "49%" }}> <span style={DEMONSTRATION_STYLE}>Default</span> <ElImage src={src} style={{ maxWidth: 300, maxHeight: 200, padding: "0 5px" }} /> </div> <div style={{ ...EQUAL_BLOCK_STYLE, width: "49%", borderRight: "none", }} > <span style={DEMONSTRATION_STYLE}>Custom</span> <ElImage src={src} style={{ maxWidth: 300, maxHeight: 200, padding: "0 5px" }} renderPlaceholder={() => ( <div style={slotStyle}> Loading <span style={{ animation: "dot 2s infinite steps(3, start)", overflow: "hidden", }} > ... </span> </div> )} /> </div> </div> ); } Load Failed Custom failed content when error occurs to image load by slot = error and slot = viewer-error.
export function ImageLoadFailed() { const [showPreview, setShowPreview] = useState(false); const srcList = [ "https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg", "https://errorSrc", ]; const errorSlotStyle: CSSProperties = { display: "flex", justifyContent: "center", alignItems: "center", flexDirection: "column", fontSize: 30, height: 200, background: "#fff", }; const imageStyle: CSSProperties = { maxWidth: 300, maxHeight: 200, width: "100%", }; return ( <ElConfigProvider locale={en}> <div style={{ display: "flex", gap: 8 }}> <ElImage style={imageStyle} /> <ElImage style={imageStyle} renderError={() => ( <div style={errorSlotStyle}> <ElIcon> <Picture /> </ElIcon> </div> )} /> <ElImage style={imageStyle} src={srcList[0]} previewSrcList={srcList} showProgress renderViewerError={({ activeIndex, src }: ImageViewerErrorScope) => ( <div style={{ ...errorSlotStyle, color: "#000" }}> <ElIcon> <Picture /> </ElIcon> <span> this is viewer-error slot. current index: {activeIndex}. src: {src} </span> </div> )} /> <ElButton onClick={() => setShowPreview(true)}>preview controlled</ElButton> {showPreview && ( <ElImageViewer showProgress urlList={srcList} onClose={() => setShowPreview(false)} renderViewerError={({ activeIndex, src }: ImageViewerErrorScope) => ( <div style={{ ...errorSlotStyle, color: "#000" }}> <ElIcon> <Picture /> </ElIcon> <span> this is viewer-error slot. current index: {activeIndex}. src: {src} </span> </div> )} /> )} </div> </ElConfigProvider> ); } Lazy Load Native loading has been supported since 2.2.3 , you can use loading = "lazy" to replace lazy = true.
If the current browser supports native lazy loading, the native lazy loading will be used first, otherwise will be implemented through scroll.
Use lazy load by lazy = true. Image will load until scroll into view when set. You can indicate scroll container that adds scroll listener to by scroll-container. If undefined, will be the nearest parent container whose overflow property is auto or scroll.
export function ImageLazyLoad() { return ( <div style={{ height: 400, overflowY: "auto" }}> {SRC_LIST.map((url, index) => ( <ElImage key={url} src={url} lazy style={{ display: "block", minHeight: 200, marginBottom: index < SRC_LIST.length - 1 ? 10 : 0, }} /> ))} </div> ); } Image Preview allow big image preview by setting previewSrcList prop. You can initialize the position of the first picture previewed by initial-index. The default initial position is 0.
export function ImagePreview() { return ( <div> <ElImage style={IMAGE_BOX_STYLE} src={PREVIEW_URL} zoomRate={1.2} maxScale={7} minScale={0.2} previewSrcList={SRC_LIST} showProgress initialIndex={4} fit="cover" /> </div> ); } Manually Open Preview 2.9.4 openPreview with showPreview method preview controlled
export function ImageManuallyPreview() { const imageRef = useRef<ImageExpose>(null); const [showPreview, setShowPreview] = useState(false); return ( <div style={{ display: "flex", gap: 48 }}> <div style={{ display: "grid", gap: 12 }}> <ElButton onClick={() => imageRef.current?.showPreview()}> openPreview with showPreview method </ElButton> <ElImage ref={imageRef} style={IMAGE_BOX_STYLE} src={PREVIEW_URL} showProgress previewSrcList={SRC_LIST} fit="cover" /> </div> <div> <ElButton onClick={() => setShowPreview(true)}>preview controlled</ElButton> {showPreview && ( <ElImageViewer urlList={SRC_LIST} showProgress initialIndex={4} onClose={() => setShowPreview(false)} /> )} </div> </div> ); } Custom toolbar content by toolbar slot, starting from version 2.9.7 , the slot has a new setActiveItem function, which can be switched according to the index.
export function ImageCustomToolbar() { const download = (index: number) => { const url = SRC_LIST[index]; const suffix = url.slice(url.lastIndexOf(".")); const filename = Date.now() + suffix; fetch(url) .then((response) => response.blob()) .then((blob) => { const blobUrl = window.URL.createObjectURL(new Blob([blob])); const link = document.createElement("a"); link.href = blobUrl; link.download = filename; document.body.appendChild(link); link.click(); window.URL.revokeObjectURL(blobUrl); link.remove(); }); }; return ( <div> <ElImage style={IMAGE_BOX_STYLE} src={PREVIEW_URL} previewSrcList={SRC_LIST} fit="cover" showProgress renderToolbar={(scope: ImageViewerToolbarScope) => ( <> <ElIcon onClick={scope.prev}> <Back /> </ElIcon> <ElIcon onClick={scope.next}> <Right /> </ElIcon> <ElIcon onClick={() => scope.setActiveItem(SRC_LIST.length - 1)}> <DArrowRight /> </ElIcon> <ElIcon onClick={() => scope.actions("zoomOut")}> <ZoomOut /> </ElIcon> <ElIcon onClick={() => scope.actions("zoomIn", { enableTransition: false, zoomRate: 2 }) } > <ZoomIn /> </ElIcon> <ElIcon onClick={() => scope.actions("clockwise", { rotateDeg: 180, enableTransition: false, }) } > <RefreshRight /> </ElIcon> <ElIcon onClick={() => scope.actions("anticlockwise")}> <RefreshLeft /> </ElIcon> <ElIcon onClick={scope.reset}> <Refresh /> </ElIcon> <ElIcon onClick={() => download(scope.activeIndex)}> <Download /> </ElIcon> </> )} /> </div> ); } Custom progress 2.9.4 By setting the show-progress prop to control whether to display progress when previewing an image. After version 2.9.8 , the progress content will be displayed as long as the progress slot is used.
export function ImageCustomProgress() { return ( <div> <ElImage style={IMAGE_BOX_STYLE} src={PREVIEW_URL} previewSrcList={SRC_LIST} fit="cover" renderProgress={({ activeIndex, total }: ImageViewerProgressScope) => ( <span>{activeIndex + 1 + "-" + total}</span> )} /> </div> ); } Image API
Image Attributes
Name Description Type Default src image source, same as native. string'' fit indicate how the image should be resized to fit its container, same as object-fit . enum'' hide-on-click-modal when enabling preview, use this flag to control whether clicking on backdrop can exit preview mode. booleanfalse loading 2.2.3 Indicates how the browser should load the image, same as native . enum— lazy whether to use lazy load. booleanfalse scroll-container the container to add scroll listener when using lazy load. By default, the container to add scroll listener when using lazy load. stringobject— alt native attribute alt. string— referrerpolicy native attribute referrerPolicy . string— crossorigin native attribute crossorigin . enum— preview-src-list allow big image preview. array[] z-index set image preview z-index. number— initial-index initial preview image index, less than the length of url-list. number0 close-on-press-escape whether the image-viewer can be closed by pressing ESC. booleantrue preview-teleported whether to append image-viewer to body. A nested parent element attribute transform should have this attribute set to true. booleanfalse infinite whether the viewer preview is infinite. booleantrue zoom-rate the zoom rate of the image viewer zoom event. number1.2 scale 2.11.3 the preview image scale. number1 min-scale 2.4.0 the min scale of the image viewer zoom event. number0.2 max-scale 2.4.0 the max scale of the image viewer zoom event. number7 show-progress 2.9.4 whether to display the preview image progress content. booleanfalse
Image Events
Name Description Type load same as native load. Functionerror same as native error. Functionswitch trigger when switching images. Functionclose trigger when clicking on close button or when hide-on-click-modal enabled clicking on backdrop. Functionshow trigger when the viewer displays Function
Image Slots
Name Description Type placeholder custom placeholder content when image hasn't loaded yet. - error custom image load failed content. - image viewer slots when you allow big image preview, image viewer slots all can be used. -
Image Exposes
Name Description Type showPreview 2.9.4 manually open preview big image Function
Image Viewer API
Image Viewer Attributes
Name Description Type Default url-list preview link list. array[] z-index preview backdrop z-index. numberstring— initial-index the initial preview image index, less than or equal to the length of url-list. number0 infinite whether preview is infinite. booleantrue hide-on-click-modal whether user can emit close event when clicking backdrop. booleanfalse teleported whether to append image itself to body. A nested parent element attribute transform should have this attribute set to true. booleanfalse zoom-rate 2.2.27 the zoom rate of the image viewer zoom event. number1.2 scale 2.11.3 the preview image scale. number1 min-scale 2.4.0 the min scale of the image viewer zoom event. number0.2 max-scale 2.4.0 the max scale of the image viewer zoom event. number7 close-on-press-escape whether the image-viewer can be closed by pressing ESC. booleantrue show-progress 2.9.4 whether to display the preview image progress content booleanfalse
Image Viewer Events
Name Description Type close trigger when clicking on close button or when hide-on-click-modal enabled clicking on backdrop. Functionerror 2.11.3 same as native error. Functionswitch trigger when switching images. Functionrotate 2.3.13 trigger when rotating images. Function
Image Viewer Slots
Name Description Type viewer custom content - progress 2.9.4 custom progress content (Priority is higher than show-progress prop) objecttoolbar 2.9.4 custom toolbar content objectviewer-error 2.11.3 custom image load failed content. object
Image Viewer Exposes
Name Description Type setActiveItem manually switch image Function
Type Declarations
Show declarations
type ImageViewerAction = 'zoomIn' | 'zoomOut' | 'clockwise' | 'anticlockwise'
type ImageViewerActionOptions = {
enableTransition ?: boolean
zoomRate ?: number
rotateDeg ?: number
}
