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.

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

Image

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 (33)

Fast and Element Plus 2.14.6 props are merged below. Fast changes appear first; native props that are not forwarded remain visible for compatibility review.

Property	Source	Description	Type	Default
method	Fast override	Upload HTTP method.	String	FastpostELpost
showFileList	Fast override	Show file list.	Boolean	FastfalseELtrue
accept	Fast override	Accepted file types, using native input accept syntax.	String	FastGenerated at runtimeEL""
fileList	Fast override	Two-way upload file-list model.	Array	Fast[]EL[]
listType	Fast override	Upload file-list style.	String	FastpictureELtext
httpRequest	Fast override	Custom upload implementation; highest priority.	Function	Fast—EL—
limit	Fast override	Maximum files to upload or select.	Number	Fast—EL—
beforeUpload	Fast override	Validation callback before upload.	Function	Fast—EL—
modelValue	Fast addition	v-model value.	String	—
maxSize	Fast addition	Maximum file size in KB.	String / Number	2048
uploadApi	Fast addition	Fast upload function.	Function	—
uploadUrl	Fast addition	Built-in Fast upload URL.	String	—
width	Fast addition	Component width.	String / Number	150
height	Fast addition	Component height.	String / Number	150
action	EL native	Upload request URL.	String	#
headers	EL native	Upload request headers.	Object	—
data	EL native	Component data.	Object / Function / Promise	—
multiple	EL native	Allow multiple selection.	Boolean	false
name	EL native	Icon name, CSS class, or external SVG URL.	String	file
drag	EL native	whether to activate drag and drop mode.	Boolean	false
withCredentials	EL native	whether cookies are sent.	Boolean	false
autoUpload	EL native	Upload immediately after file selection.	Boolean	true
disabled	EL native	Disable the component or current option.	Boolean	false
directory	EL native	whether 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.	Boolean	false
beforeRemove	EL native	Callback before removing an uploaded file.	Function	—
onRemove	EL native	hook function when files are removed.	Function	—
onChange	EL native	hook function when select file or upload file success or upload file fail.	Function	—
onPreview	EL native	hook function when clicking the uploaded files.	Function	—
onSuccess	EL native	hook function when uploaded successfully.	Function	—
onProgress	EL native	hook function when some progress occurs.	Function	—
onError	EL native	hook function when some errors occurs.	Function	—
onExceed	EL native	hook function when limit is exceeded.	Function	—
crossorigin	EL native	native attribute crossorigin.	String	—

Events（2）

Name	Source	Description	Parameters / type
update:modelValue	Fast addition	Updates v-model.	—
update:fileList	Fast addition	Updates the upload file list.	—

Slots（4）

Name	Source	Description	Parameters / type
default	EL native	Default component content.	—
trigger	EL native · not forwarded	content which triggers file dialog.	—
tip	EL native · not forwarded	content of tips.	—
file	EL native · not forwarded	content of thumbnail template.	{ file: UploadFile, index: number }

Expose（9）

Name	Source	Description	Parameters / type
abort	EL native	Aborts uploads for one or all files.	—
submit	EL native	Submits upload files in ready state.	—
clearFiles	EL native	Clears upload files, optionally by status.	—
handleStart	EL native	Adds a raw file to the upload queue.	—
handleRemove	EL native	Removes a file from the upload list.	—
loading	Fast addition	Fast business loading state.	—
fileList	Fast addition	Current upload file list.	—
preview	Fast addition	Previews an uploaded image.	—
previewList	Fast addition	Current previewable image URLs.	—

FaUploadImage instance methods

abort Abort

Aborts upload requests.

Signature

abort(file?: UploadFile): void;

Example

<template>
	<FaUploadImage ref="componentRef" />
</template>

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

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

Input

Input	Type	Required / default	Description
file	UploadFile | undefined	Optional	Upload file to abort or remove; omit to abort all requests.

Returns

Value	Type	Description
result	void	No return value.

submit Submit

Manually submits the file list.

Signature

submit(): void;

Example

<template>
	<FaUploadImage ref="componentRef" />
</template>

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

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

Input

This method has no input parameters.

Returns

Value	Type	Description
result	void	No return value.

clearFiles Clear

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

Signature

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

Example

<template>
	<FaUploadImage ref="componentRef" />
</template>

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

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

Input

Input	Type	Required / default	Description
states	UploadStatus[] | undefined	Optional	Upload statuses to clear.

Returns

Value	Type	Description
result	void	No return value.

handleStart Queue

Manually starts handling a selected file.

Signature

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

Example

<template>
	<FaUploadImage ref="componentRef" />
</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() });
componentRef.value?.handleStart(rawFile);
</script>

Input

Input	Type	Required / default	Description
rawFile	UploadRawFile	Required	Browser-selected raw file with an Element Plus upload uid.

Returns

Value	Type	Description
result	void	No return value.

handleRemove Remove

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

Signature

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

Example

<template>
	<FaUploadImage ref="componentRef" />
</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() });
componentRef.value?.handleRemove(rawFile);
</script>

Input

Input	Type	Required / default	Description
file	UploadRawFile | UploadFile	Required	Upload file to abort or remove; omit to abort all requests.

Returns

Value	Type	Description
result	void	No return value.