Skip to content

FaUploadImage ​

Single-file image upload with explicit dimensions, replacement, removal, preview and a string | null model. Dragging is disabled by default; enable drag when needed. Manual upload validates type and size immediately on selection. width and height affect the image frame only. Hint text uses the outer available width below the frame and does not count toward height. The loading overlay covers only the image frame; borders use the Element Plus theme.

Since 2.0.28, trigger, tip and file are customizable. With show-file-list enabled, #file receives { file, index }. The built-in preview also calls onPreview(file).

Read the uploaded URL from v-model. onChange(uploadFile, uploadFiles) retains the native file-state callback.

Image

Interactive example
View code
Vue
<template>
	<FaUploadImage v-model="image" :upload-api="uploadApi" :width="220" :height="140" />
</template>

<script setup lang="ts">
import { ref } from "vue";

const createImage = (text: string, color: string): string =>
	`data:image/svg+xml;charset=UTF-8,${encodeURIComponent(
		`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 200"><rect width="320" height="200" rx="18" fill="${color}"/><text x="160" y="115" text-anchor="middle" font-size="38" fill="white">${text}</text></svg>`
	)}`;
const image = ref<string | null>(createImage("封面图", "#409eff"));
const uploadApi = (formData: FormData): Promise<string> => {
	const file = formData.get("file");
	if (!(file instanceof File)) return Promise.reject(new TypeError("未找到上传图片"));
	try {
		return Promise.resolve(URL.createObjectURL(file));
	} catch (error) {
		return Promise.reject(error);
	}
};
</script>

FaUploadImage Complete API

Props

EL defaults refer to Element Plus before Fast is imported. 2.14.7

PropertySourceDescriptionTypeDefault
methodFast overrideUpload HTTP method.StringFastpostELpost
showFileListFast overrideShow file list.BooleanFastfalseELtrue
acceptFast overrideAccepted file types, using native input accept syntax.StringFastGenerated at runtimeEL""
fileListFast overrideTwo-way upload file-list model.ArrayFast[]EL[]
listTypeFast overrideUpload file-list style.StringFastpictureELtext
httpRequestFast overrideCustom upload implementation; highest priority.FunctionFast—EL—
limitFast overrideMaximum files to upload or select.NumberFast—EL—
beforeUploadFast overrideValidation callback before upload.FunctionFast—EL—
modelValueFast additionv-model value.String—
maxSizeFast additionMaximum file size in KB.String / Number2048
uploadApiFast additionFast upload function.Function—
uploadUrlFast additionBuilt-in Fast upload URL.String—
widthFast additionComponent width.String / Number150
heightFast additionComponent height.String / Number150
actionEL nativeUpload request URL.String#
headersEL nativeUpload request headers.Object—
dataEL nativeComponent data.Object / Function / Promise—
multipleEL nativeAllow multiple selection.Booleanfalse
nameEL nativeIcon name, CSS class, or external SVG URL.Stringfile
dragEL nativewhether to activate drag and drop mode.Booleanfalse
withCredentialsEL nativewhether cookies are sent.Booleanfalse
autoUploadEL nativeUpload immediately after file selection.Booleantrue
disabledEL nativeDisable the component or current option.Booleanfalse
directoryEL nativewhether to support uploading directory. After enabling it, only folders can be selected, and after selecting a folder, the files within the folder will be flattened.Booleanfalse
beforeRemoveEL nativeCallback before removing an uploaded file.Function—
onRemoveEL nativehook function when files are removed.Function—
onChangeEL nativehook function when select file or upload file success or upload file fail.Function—
onPreviewEL nativehook function when clicking the uploaded files.Function—
onSuccessEL nativehook function when uploaded successfully.Function—
onProgressEL nativehook function when some progress occurs.Function—
onErrorEL nativehook function when some errors occurs.Function—
onExceedEL nativehook function when limit is exceeded.Function—
crossoriginEL nativenative attribute crossorigin.String—

Events

NameSourceDescriptionParameters / type
update:modelValueFast additionUpdates v-model.—
update:fileListFast additionUpdates the upload file list.—

Slots

NameSourceDescriptionParameters / type
defaultEL nativeDefault component content.—
triggerEL native · not forwardedcontent which triggers file dialog.—
tipEL native · not forwardedcontent of tips.—
fileEL native · not forwardedcontent of thumbnail template.{ file: UploadFile, index: number }

Exposes

NameSourceDescriptionParameters / type
abortEL nativeAborts uploads for one or all files.—
submitEL nativeSubmits upload files in ready state.—
clearFilesEL nativeClears upload files, optionally by status.—
handleStartEL nativeAdds a raw file to the upload queue.—
handleRemoveEL nativeRemoves a file from the upload list.—
loadingFast additionFast business loading state.—
fileListFast additionCurrent upload file list.—
previewFast additionPreviews an uploaded image.—
previewListFast additionCurrent previewable image URLs.—

FaUploadImage instance methods ​

These are call snippets. Use rows, options and fields from your actual data.

abort Abort ​

Aborts upload requests.

Signature ​

ts
abort(file?: UploadFile): void;

Example ​

vue
<template>
	<FaUploadImage ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaUploadImage } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaUploadImage>>();
function handleExample() {
	componentRef.value?.abort(undefined);
}
</script>

Input ​

InputTypeRequired / defaultDescription
fileUploadFile | undefinedOptionalUpload file to abort or remove; omit to abort all requests.

Returns ​

ValueTypeDescription
resultvoidNo return value.

submit Submit ​

Manually submits the file list.

Signature ​

ts
submit(): void;

Example ​

vue
<template>
	<FaUploadImage ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaUploadImage } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaUploadImage>>();
function handleExample() {
	componentRef.value?.submit();
}
</script>

Input: No parameters.

Returns: void.

clearFiles Clear ​

Clears the uploaded-file list; do not call inside before-upload.

Signature ​

ts
clearFiles(states?: import("element-plus").UploadStatus[]): void;

Example ​

vue
<template>
	<FaUploadImage ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaUploadImage } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaUploadImage>>();
function handleExample() {
	componentRef.value?.clearFiles(["success"]);
}
</script>

Input ​

InputTypeRequired / defaultDescription
statesUploadStatus[] | undefinedOptionalUpload statuses to clear.

Returns ​

ValueTypeDescription
resultvoidNo return value.

handleStart Queue ​

Manually starts handling a selected file.

Signature ​

ts
handleStart(rawFile: import("element-plus").UploadRawFile): void;

Example ​

vue
<template>
	<FaUploadImage ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaUploadImage } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaUploadImage>>();
const rawFile = Object.assign(new File(["Fast"], "fast.txt", { type: "text/plain" }), { uid: Date.now() });
function handleExample() {
	componentRef.value?.handleStart(rawFile);
}
</script>

Input ​

InputTypeRequired / defaultDescription
rawFileUploadRawFileRequiredBrowser-selected raw file with an Element Plus upload uid.

Returns ​

ValueTypeDescription
resultvoidNo return value.

handleRemove Remove ​

Manually removes a file; file and rawFile have been merged.

Signature ​

ts
handleRemove(file: UploadFile | import("element-plus").UploadRawFile): void;

Example ​

vue
<template>
	<FaUploadImage ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaUploadImage } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaUploadImage>>();
const rawFile = Object.assign(new File(["Fast"], "fast.txt", { type: "text/plain" }), { uid: Date.now() });
function handleExample() {
	componentRef.value?.handleRemove(rawFile);
}
</script>

Input ​

InputTypeRequired / defaultDescription
fileUploadRawFile | UploadFileRequiredUpload file to abort or remove; omit to abort all requests.

Returns ​

ValueTypeDescription
resultvoidNo return value.