FaImage
Enables lazy loading, image preview and Teleport by default, and adds image-service URL conversion and the complete Viewer slots.
Since 2.0.28, preview-src-list accepts multiple original images and falls back to src when empty. preview=false disables preview. #viewerPlaceholder and #viewerError render while the preview is loading or after an error. Both receive { activeIndex, src }. When upgrading from 2.0.27, rename #viewer-error to #viewerError.
Image Modes
Interactive exampleView code
<template>
<div class="demo-image-grid">
<div>
<FaImage :src="image" original fit="cover" style="width: 100%; height: 140px" />
<span>{{ english ? "Cover · click to preview" : "Cover · 点击预览" }}</span>
</div>
<div><FaImage :src="image" original fit="contain" style="width: 100%; height: 140px" /><span>Contain</span></div>
<div>
<FaImage src="data:image/png;base64,AA==" original :preview="false" style="width: 100%; height: 140px">
<template #error
><div class="demo-image-error">{{ english ? "Custom image error" : "自定义加载失败" }}</div></template
>
</FaImage>
<span>{{ english ? "Error slot" : "错误插槽" }}</span>
</div>
</div>
</template>
<script setup lang="ts">
import { computed } from "vue";
const props = defineProps<{ language?: string }>();
const english = computed(() => props.language === "en-US");
const image = `data:image/svg+xml;charset=UTF-8,${encodeURIComponent(
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 360"><defs><linearGradient id="g"><stop stop-color="#409eff"/><stop offset="1" stop-color="#36cfc9"/></linearGradient></defs><rect width="640" height="360" fill="url(#g)"/><circle cx="500" cy="80" r="45" fill="#fff" opacity=".65"/><text x="48" y="205" font-size="54" fill="white">Fast.Element.Plus</text></svg>'
)}`;
</script>FaImage Complete API
Props
EL defaults refer to Element Plus before Fast is imported. 2.14.7
| Property | Source | Description | Type | Default |
|---|---|---|---|---|
hideOnClickModal | Fast override | Close image preview when its overlay is clicked. | Boolean | FasttrueELfalse |
src | Fast override | Image URL or Base64 content. | String | Fast""EL"" |
lazy | Fast override | Enable lazy loading. | Boolean | FasttrueELfalse |
previewSrcList | Fast override | Image preview list. | Array | Fast[]EL[] |
previewTeleported | Fast override | Append image preview to body. | Boolean | FasttrueELfalse |
base64 | Fast addition | Interpret the value as Base64 image content. | Boolean | false |
original | Fast addition | Use the original image URL. | Boolean | false |
normal | Fast addition | Use the standard-image URL suffix. | Boolean | false |
small | Fast addition | Use the small-image URL suffix. | Boolean | false |
thumb | Fast addition | Use the thumbnail URL suffix. | Boolean | false |
preview | Fast addition | Allow image preview. | Boolean | true |
fit | EL native | How content fits its container. | String | "" |
loading | EL native | Loading state. | String | — |
scrollContainer | EL native | the container to add scroll listener when using lazy load. By default, the container to add scroll listener when using lazy load. | String / Object | — |
zIndex | EL native | set image preview z-index. | Number | — |
initialIndex | EL native | initial preview image index, less than the length of url-list. | Number | 0 |
infinite | EL native | whether the viewer preview is infinite. | Boolean | true |
closeOnPressEscape | EL native | whether the image-viewer can be closed by pressing ESC. | Boolean | true |
zoomRate | EL native | the zoom rate of the image viewer zoom event. | Number | 1.2 |
scale | EL native | the preview image scale. | Number | 1 |
minScale | EL native | the min scale of the image viewer zoom event. | Number | 0.2 |
maxScale | EL native | the max scale of the image viewer zoom event. | Number | 7 |
showProgress | EL native | whether to display the preview image progress content. | Boolean | false |
crossorigin | EL native | native attribute crossorigin. | String | — |
Events
| Name | Source | Description | Parameters / type |
|---|---|---|---|
load | EL native | Resource loading succeeds. | — |
error | EL native | Resource loading or component processing fails. | — |
switch | EL native | Image viewer switches images. | — |
close | EL native | Closing flow completes. | — |
show | EL native | Image viewer appears. | — |
Slots
| Name | Source | Description | Parameters / type |
|---|---|---|---|
placeholder | EL native | Placeholder during image loading. | — |
error | EL native | Custom validation-error or image-load-error content. | — |
viewer({ src }) | EL native | Custom image-viewer content. | ({ src }) |
progress | EL native | Custom image-loading progress content. | — |
toolbar | EL native | Custom image-preview toolbar. | — |
viewer-error | EL native | Custom image-viewer load-error content. | — |
image viewer slots | EL native · not forwarded | when you allow big image preview, image viewer slots all can be used, except default. | — |
Exposes
| Name | Source | Description | Parameters / type |
|---|---|---|---|
showPreview | EL native | Opens the ElImage viewer. | — |
FaImage instance methods
These are call snippets. Use rows, options and fields from your actual data.
showPreview Preview
Manually opens the image preview.
Signature
ts
showPreview(): void;Example
vue
<template>
<FaImage ref="componentRef" />
<button type="button" @click="handleExample">Call method</button>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { FaImage } from "fast-element-plus";
const componentRef = ref<InstanceType<typeof FaImage>>();
function handleExample() {
componentRef.value?.showPreview();
}
</script>Input: No parameters.
Returns: void.
