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

export function UploadBasic() {  const [fileList, setFileList] = useState<UploadUserFile[]>(INITIAL_FILES);  const handleRemove: UploadProps["onRemove"] = (file, uploadFiles) => {    console.log(file, uploadFiles);  };  const handlePreview: UploadProps["onPreview"] = (uploadFile) => {    console.log(uploadFile);  };  const handleExceed: UploadProps["onExceed"] = (files, uploadFiles) => {    message.warning(      `The limit is 3, you selected ${files.length} files this time, add up to ${        files.length + uploadFiles.length      } totally`,    );  };  const beforeRemove: UploadProps["beforeRemove"] = (uploadFile) => {    return MessageBox.confirm(`Cancel the transfer of ${uploadFile.name} ?`).then(      () => true,      () => false,    );  };  return (    <ElUpload      fileList={fileList}      onFileListChange={setFileList}      action={ACTION}      multiple      onPreview={handlePreview}      onRemove={handleRemove}      beforeRemove={beforeRemove}      limit={3}      onExceed={handleExceed}      tip={        <div className="el-upload__tip">          jpg/png files with a size less than 500KB.        </div>      }    >      <ElButton type="primary">Click to upload</ElButton>    </ElUpload>  );}

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

export function UploadLimitCover() {  const uploadRef = useRef<UploadExpose>(null);  const handleExceed: UploadProps["onExceed"] = (files) => {    uploadRef.current?.clearFiles();    const file = files[0] as UploadRawFile;    file.uid = genFileId();    uploadRef.current?.handleStart(file);  };  const submitUpload = () => {    uploadRef.current?.submit();  };  return (    <ElUpload      ref={uploadRef}      action={ACTION}      limit={1}      onExceed={handleExceed}      autoUpload={false}      trigger={<ElButton type="primary">select file</ElButton>}      tip={        <div className="el-upload__tip" style={{ color: "#f87171" }}>          limit 1 file, new file will cover the old file        </div>      }    >      <ElButton type="success" style={gapLeftStyle} onClick={submitUpload}>        upload to server      </ElButton>    </ElUpload>  );}

User Avatar

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

export function UploadAvatar() {  const [imageUrl, setImageUrl] = useState("");  const handleAvatarSuccess: UploadProps["onSuccess"] = (_response, uploadFile) => {    if (uploadFile.raw) setImageUrl(URL.createObjectURL(uploadFile.raw));  };  const beforeAvatarUpload: UploadProps["beforeUpload"] = (rawFile) => {    if (rawFile.type !== "image/jpeg") {      message.error("Avatar picture must be JPG format!");      return false;    } else if (rawFile.size / 1024 / 1024 > 2) {      message.error("Avatar picture size can not exceed 2MB!");      return false;    }    return true;  };  return (    <ElUpload      className={`avatar-uploader ${styles.avatarUploader}`}      action={ACTION}      showFileList={false}      onSuccess={handleAvatarSuccess}      beforeUpload={beforeAvatarUpload}    >      {imageUrl ? (        <img src={imageUrl} style={avatarImgStyle} alt="" />      ) : (        <ElIcon className="avatar-uploader-icon" style={avatarIconStyle}>          <Plus />        </ElIcon>      )}    </ElUpload>  );}

Photo Wall

Use list-type to change the fileList style.

export function UploadPhotoWall() {  const [fileList, setFileList] = useState<UploadUserFile[]>(PHOTO_WALL_FILES);  const [dialogImageUrl, setDialogImageUrl] = useState("");  const [dialogVisible, setDialogVisible] = useState(false);  const handleRemove: UploadProps["onRemove"] = (uploadFile, uploadFiles) => {    console.log(uploadFile, uploadFiles);  };  const handlePictureCardPreview: UploadProps["onPreview"] = (uploadFile) => {    setDialogImageUrl(uploadFile.url ?? "");    setDialogVisible(true);  };  return (    <>      <ElUpload        fileList={fileList}        onFileListChange={setFileList}        action={ACTION}        listType="picture-card"        onPreview={handlePictureCardPreview}        onRemove={handleRemove}      >        <ElIcon>          <Plus />        </ElIcon>      </ElUpload>      <ElDialog visible={dialogVisible} onVisibleChange={setDialogVisible}>        <img src={dialogImageUrl} alt="Preview Image" style={{ width: "100%" }} />      </ElDialog>    </>  );}

Custom Thumbnail

Use scoped-slot to change default thumbnail template.

export function UploadCustomThumbnail() {  const [dialogImageUrl, setDialogImageUrl] = useState("");  const [dialogVisible, setDialogVisible] = useState(false);  const handleRemove = (file: UploadFile) => {    console.log(file);  };  const handlePictureCardPreview = (file: UploadFile) => {    setDialogImageUrl(file.url ?? "");    setDialogVisible(true);  };  const handleDownload = (file: UploadFile) => {    console.log(file);  };  return (    <>      <ElUpload        action="#"        listType="picture-card"        autoUpload={false}        renderFile={(file) => (          <div>            <img className="el-upload-list__item-thumbnail" src={file.url} alt="" />            <span className="el-upload-list__item-actions">              <span                className="el-upload-list__item-preview"                onClick={() => handlePictureCardPreview(file)}              >                <ElIcon>                  <ZoomIn />                </ElIcon>              </span>              <span                className="el-upload-list__item-delete"                onClick={() => handleDownload(file)}              >                <ElIcon>                  <Download />                </ElIcon>              </span>              <span                className="el-upload-list__item-delete"                onClick={() => handleRemove(file)}              >                <ElIcon>                  <Delete />                </ElIcon>              </span>            </span>          </div>        )}      >        <ElIcon>          <Plus />        </ElIcon>      </ElUpload>      <ElDialog visible={dialogVisible} onVisibleChange={setDialogVisible}>        <img src={dialogImageUrl} alt="Preview Image" style={{ width: "100%" }} />      </ElDialog>    </>  );}

File List with Thumbnail

jpg/png files with a size less than 500kb

food.jpeg
food2.jpeg

export function UploadFileListWithThumbnail() {  const [fileList, setFileList] = useState<UploadUserFile[]>(PICTURE_FILES);  const handleRemove: UploadProps["onRemove"] = (uploadFile, uploadFiles) => {    console.log(uploadFile, uploadFiles);  };  const handlePreview: UploadProps["onPreview"] = (file) => {    console.log(file);  };  return (    <ElUpload      fileList={fileList}      onFileListChange={setFileList}      action={ACTION}      onPreview={handlePreview}      onRemove={handleRemove}      listType="picture"      tip={        <div className="el-upload__tip">          jpg/png files with a size less than 500kb        </div>      }    >      <ElButton type="primary">Click to upload</ElButton>    </ElUpload>  );}

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

export function UploadFileList() {  const [fileList, setFileList] = useState<UploadUserFile[]>(PICTURE_FILES);  const handleChange: UploadProps["onChange"] = () => {    setFileList((prev) => prev.slice(-3));  };  return (    <ElUpload      fileList={fileList}      onFileListChange={setFileList}      action={ACTION}      onChange={handleChange}      tip={        <div className="el-upload__tip">          jpg/png files with a size less than 500kb        </div>      }    >      <ElButton type="primary">Click to upload</ElButton>    </ElUpload>  );}

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

export function UploadDragAndDrop() {  return (    <ElUpload      action={ACTION}      drag      multiple      tip={        <div className="el-upload__tip">          jpg/png files with a size less than 500kb        </div>      }    >      <ElIcon className="el-icon--upload">        <UploadFilled />      </ElIcon>      <div className="el-upload__text">        Drop file here or <em>click to upload</em>      </div>    </ElUpload>  );}

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

export function UploadDirectory() {  const handleChange = (uploadFile: UploadFile, uploadFiles: UploadFile[]) => {    console.log(uploadFile, uploadFiles);  };  return (    <ElUpload      action={ACTION}      drag      directory      multiple      onChange={handleChange}    >      <ElIcon className="el-icon--upload">        <UploadFilled />      </ElIcon>      <div className="el-upload__text">        Drop directory here or <em>click to upload</em>      </div>    </ElUpload>  );}

Manual Upload

jpg/png files with a size less than 500kb

export function UploadManual() {  const uploadRef = useRef<UploadExpose>(null);  const submitUpload = () => {    uploadRef.current?.submit();  };  return (    <ElUpload      ref={uploadRef}      action={ACTION}      autoUpload={false}      trigger={<ElButton type="primary">select file</ElButton>}      tip={        <div className="el-upload__tip">          jpg/png files with a size less than 500kb        </div>      }    >      <ElButton type="success" style={gapLeftStyle} onClick={submitUpload}>        upload to server      </ElButton>    </ElUpload>  );}

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. When a `file` is specified, abort the corresponding pending upload; when no file is specified, abort all pending uploads.	`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] | 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
}