Upload

Upload files by clicking or drag-and-drop.

Basic Usage

Customize upload button type and text using slot. Set limit and on-exceed to limit the maximum number of uploads allowed and specify method when the limit is exceeded. Plus, you can abort removing a file in the before-remove hook.

jpg/png files with a size less than 500KB.

element-plus-logo.svg
element-plus-logo2.svg

Cover Previous File

Set limit and on-exceed to automatically replace the previous file when select a new file.

limit 1 file, new file will cover the old file

User Avatar

Use before-upload hook to limit the upload file format and size.

Photo Wall

Use list-type to change the fileList style.

Custom Thumbnail

Use scoped-slot to change default thumbnail template.

File List with Thumbnail

jpg/png files with a size less than 500kb

food.jpeg
food2.jpeg

File List Control

Use on-change hook function to control upload file list.

jpg/png files with a size less than 500kb

food.jpeg
food2.jpeg

Drag to Upload

You can drag your file to a certain area to upload it.

Drop file here or click to upload

jpg/png files with a size less than 500kb

Upload Directory 2.13.1

Enable folder upload via the directory prop.

After enabling it, only folders can be selected, and after selecting a folder, the files within the folder will be flattened.

Drop directory here or click to upload

Manual Upload

jpg/png files with a size less than 500kb

API

Attributes

Name	Description	Type	Default
action required	request URL.	`string`	#
headers	request headers.	`object`	—
method	set upload request method.	`string`	post
multiple	whether uploading multiple files is permitted.	`boolean`	false
data	additions options of request. support `Awaitable` data and `Function` since v2.3.13.	`object` / `Function`	{}
name	key name for uploaded file.	`string`	file
with-credentials	whether cookies are sent.	`boolean`	false
show-file-list	whether to show the uploaded file list.	`boolean`	true
drag	whether to activate drag and drop mode.	`boolean`	false
accept	accepted file types, will not work when `thumbnail-mode === true`.	`string`	''
crossorigin	native attribute crossorigin.	`enum`	—
on-preview	hook function when clicking the uploaded files.	`Function`	—
on-remove	hook function when files are removed.	`Function`	—
on-success	hook function when uploaded successfully.	`Function`	—
on-error	hook function when some errors occurs.	`Function`	—
on-progress	hook function when some progress occurs.	`Function`	—
on-change	hook function when select file or upload file success or upload file fail.	`Function`	—
on-exceed	hook function when limit is exceeded.	`Function`	—
before-upload	hook function before uploading with the file to be uploaded as its parameter. If `false` is returned or a `Promise` is returned and then is rejected, uploading will be aborted.	`Function`	—
before-remove	hook function before removing a file with the file and file list as its parameters. If `false` is returned or a `Promise` is returned and then is rejected, removing will be aborted.	`Function`	—
file-list / v-model:file-list	default uploaded files.	`array`	[]
list-type	type of file list.	`enum`	text
auto-upload	whether to auto upload file.	`boolean`	true
http-request	override default xhr behavior, allowing you to implement your own upload-file's request.	`Function`	ajaxUpload see
disabled	whether to disable upload.	`boolean`	false
limit	maximum number of uploads allowed.	`number`	—
directory 2.13.1	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

Slots

Name	Description	Type
default	customize default content.	-
trigger	content which triggers file dialog.	-
tip	content of tips.	-
file	content of thumbnail template.	`object`

Exposes

Name	Description	Type
abort	cancel upload request.	`Function`
submit	upload the file list manually.	`Function`
clearFiles	clear the file list (this method is not supported in the `before-upload` hook).	`Function`
handleStart	select the file manually.	`Function`
handleRemove	remove the file manually. `file` and `rawFile` has been merged. `rawFile` will be removed in `v2.2.0`.	`Function`

Type Declarations

Show declarations

type UploadFiles = UploadFile[]

type UploadUserFile = Omit<UploadFile, 'status' | 'uid'> &
  Partial<Pick<UploadFile, 'status' | 'uid'>>

type UploadStatus = 'ready' | 'uploading' | 'success' | 'fail'

type Awaitable<T> = Promise<T> | T

type Mutable<T> = { -readonly [P in keyof T]: T[P] }

interface UploadFile {
  name: string
  percentage?: number
  status: UploadStatus
  size?: number
  response?: unknown
  uid: number
  url?: string
  raw?: UploadRawFile
}

interface UploadProgressEvent extends ProgressEvent {
  percent: number
}

interface UploadRawFile extends File {
  uid: number
  isDirectory?: boolean
}

interface UploadRequestOptions {
  action: string
  method: string
  data: Record<string, string | Blob | [string | Blob, string]>
  filename: string
  file: UploadRawFile
  headers: Headers | Record<string, string | number | null | undefined>
  onError: (evt: UploadAjaxError) => void
  onProgress: (evt: UploadProgressEvent) => void
  onSuccess: (response: any) => void
  withCredentials: boolean
}