FaUploadImages

Multiple-image upload is enabled by default. Supports count limits, previews, removal and a string[] | null model; clearing returns []. Manual mode validates type and size on selection. Drag and non-drag modes share the same add-image card layout. Card size and border colors use Element Plus defaults and can be customized with the corresponding CSS variables.

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

Images

View code

Vue

<template>
	<FaUploadImages v-model="images" :upload-api="uploadApi" :limit="5" />
</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 images = ref<string[] | null>([createImage("图 1", "#67c23a"), createImage("图 2", "#e6a23c")]);
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>

FaUploadImages Complete API

Props (31)

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
multiple	Fast override	Allow multiple selection.	Boolean	FasttrueELfalse
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	Fastpicture-cardELtext
httpRequest	Fast override	Custom upload implementation; highest priority.	Function	Fast—EL—
limit	Fast override	Maximum files to upload or select.	Number	Fast9EL—
beforeUpload	Fast override	Validation callback before upload.	Function	Fast—EL—
modelValue	Fast addition	v-model value.	Array	—
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	—
action	EL native	Upload request URL.	String	#
headers	EL native	Upload request headers.	Object	—
data	EL native	Component data.	Object / Function / Promise	—
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
showFileList	EL native	Show file list.	Boolean	true
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.	—

FaUploadImages instance methods

abort Abort

Aborts upload requests.

Signature

abort(file?: UploadFile): void;

Example

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

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

const componentRef = ref<InstanceType<typeof FaUploadImages>>();
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>
	<FaUploadImages ref="componentRef" />
</template>

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

const componentRef = ref<InstanceType<typeof FaUploadImages>>();
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>
	<FaUploadImages ref="componentRef" />
</template>

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

const componentRef = ref<InstanceType<typeof FaUploadImages>>();
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>
	<FaUploadImages ref="componentRef" />
</template>

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

const componentRef = ref<InstanceType<typeof FaUploadImages>>();
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>
	<FaUploadImages ref="componentRef" />
</template>

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

const componentRef = ref<InstanceType<typeof FaUploadImages>>();
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.