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 exampleView code
<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
| 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
| Name | Source | Description | Parameters / type |
|---|---|---|---|
update:modelValue | Fast addition | Updates v-model. | — |
update:fileList | Fast addition | Updates the upload file list. | — |
Slots
| 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 } |
Exposes
| 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
These are call snippets. Use rows, options and fields from your actual data.
abort Abort
Aborts upload requests.
Signature
abort(file?: UploadFile): void;Example
<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
| 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" />
<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
clearFiles(states?: import("element-plus").UploadStatus[]): void;Example
<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
| 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" />
<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
| 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" />
<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
| 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. |
