Skip to content

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 example
View code
Vue
<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

PropertySourceDescriptionTypeDefault
hideOnClickModalFast overrideClose image preview when its overlay is clicked.BooleanFasttrueELfalse
srcFast overrideImage URL or Base64 content.StringFast""EL""
lazyFast overrideEnable lazy loading.BooleanFasttrueELfalse
previewSrcListFast overrideImage preview list.ArrayFast[]EL[]
previewTeleportedFast overrideAppend image preview to body.BooleanFasttrueELfalse
base64Fast additionInterpret the value as Base64 image content.Booleanfalse
originalFast additionUse the original image URL.Booleanfalse
normalFast additionUse the standard-image URL suffix.Booleanfalse
smallFast additionUse the small-image URL suffix.Booleanfalse
thumbFast additionUse the thumbnail URL suffix.Booleanfalse
previewFast additionAllow image preview.Booleantrue
fitEL nativeHow content fits its container.String""
loadingEL nativeLoading state.String—
scrollContainerEL nativethe container to add scroll listener when using lazy load. By default, the container to add scroll listener when using lazy load.String / Object—
zIndexEL nativeset image preview z-index.Number—
initialIndexEL nativeinitial preview image index, less than the length of url-list.Number0
infiniteEL nativewhether the viewer preview is infinite.Booleantrue
closeOnPressEscapeEL nativewhether the image-viewer can be closed by pressing ESC.Booleantrue
zoomRateEL nativethe zoom rate of the image viewer zoom event.Number1.2
scaleEL nativethe preview image scale.Number1
minScaleEL nativethe min scale of the image viewer zoom event.Number0.2
maxScaleEL nativethe max scale of the image viewer zoom event.Number7
showProgressEL nativewhether to display the preview image progress content.Booleanfalse
crossoriginEL nativenative attribute crossorigin.String—

Events

NameSourceDescriptionParameters / type
loadEL nativeResource loading succeeds.—
errorEL nativeResource loading or component processing fails.—
switchEL nativeImage viewer switches images.—
closeEL nativeClosing flow completes.—
showEL nativeImage viewer appears.—

Slots

NameSourceDescriptionParameters / type
placeholderEL nativePlaceholder during image loading.—
errorEL nativeCustom validation-error or image-load-error content.—
viewer({ src })EL nativeCustom image-viewer content.({ src })
progressEL nativeCustom image-loading progress content.—
toolbarEL nativeCustom image-preview toolbar.—
viewer-errorEL nativeCustom image-viewer load-error content.—
image viewer slotsEL native · not forwardedwhen you allow big image preview, image viewer slots all can be used, except default.—

Exposes

NameSourceDescriptionParameters / type
showPreviewEL nativeOpens 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.