Skip to content

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.

Since 2.0.28, trigger, tip and file are customizable. #file receives { file, index } and can replace the built-in thumbnail. The built-in preview also calls onPreview(file).

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

Images

Interactive example
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

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

PropertySourceDescriptionTypeDefault
methodFast overrideUpload HTTP method.StringFastpostELpost
multipleFast overrideAllow multiple selection.BooleanFasttrueELfalse
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.StringFastpicture-cardELtext
httpRequestFast overrideCustom upload implementation; highest priority.FunctionFast—EL—
limitFast overrideMaximum files to upload or select.NumberFast9EL—
beforeUploadFast overrideValidation callback before upload.FunctionFast—EL—
modelValueFast additionv-model value.Array—
maxSizeFast additionMaximum file size in KB.String / Number2048
uploadApiFast additionFast upload function.Function—
uploadUrlFast additionBuilt-in Fast upload URL.String—
actionEL nativeUpload request URL.String#
headersEL nativeUpload request headers.Object—
dataEL nativeComponent data.Object / Function / Promise—
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
showFileListEL nativeShow file list.Booleantrue
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.—

FaUploadImages 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>
	<FaUploadImages ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

const componentRef = ref<InstanceType<typeof FaUploadImages>>();
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>
	<FaUploadImages ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

const componentRef = ref<InstanceType<typeof FaUploadImages>>();
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>
	<FaUploadImages ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

const componentRef = ref<InstanceType<typeof FaUploadImages>>();
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>
	<FaUploadImages ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</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() });
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>
	<FaUploadImages ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</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() });
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.