VUpload ​

VUpload wraps Element Plus Upload and adds built-in validation, filename sanitization, cover-file handling, and download-oriented preview behavior.

Basic Usage ​

<template>
  <v-upload
    action="/mock/upload"
    :http-request="mockUpload"
    :model-value="initialFile"
    :limit="1"
    cover-file
    accept="image/*"
    btn-text="Replace file"
  />
</template>

<script lang="ts" setup>
const initialFile = {
  fileName: 'guide-cover.png',
  fileUrl: '/images/figure-1.png',
}

const mockUpload = () => {
  return new Promise((resolve) => {
    window.setTimeout(() => {
      resolve({
        result: '/images/figure-2.png',
      })
    }, 700)
  })
}
</script>

Picture Card Download ​

<template>
  <v-upload
    action="/mock/upload"
    :http-request="mockUpload"
    :model-value="imageFiles"
    list-type="picture-card"
    accept="image/*"
    :limit="3"
    preview="download"
    :download-method="handleDownload"
  />
</template>

<script lang="ts" setup>
const imageFiles = [
  {
    fileName: 'plant-1.png',
    fileUrl: '/images/plant-1.png',
  },
  {
    fileName: 'figure-1.png',
    fileUrl: '/images/figure-1.png',
  },
]

const uploadedImages = ['/images/plant-2.png', '/images/figure-2.png']
let uploadCount = 0

const mockUpload = () => {
  return new Promise((resolve) => {
    const nextUrl = uploadedImages[uploadCount % uploadedImages.length]
    uploadCount += 1
    window.setTimeout(() => {
      resolve({
        result: nextUrl,
      })
    }, 700)
  })
}

const handleDownload = ({
  path,
  fileName,
}: {
  path: string
  fileName: string
}) => {
  const link = document.createElement('a')
  link.href = path
  link.download = fileName
  document.body.appendChild(link)
  link.click()
  document.body.removeChild(link)
}
</script>

Drag Upload ​

<template>
  <v-upload
    action="/mock/upload"
    :http-request="mockUpload"
    :drag="true"
    :multiple="true"
    accept=".xls,.xlsx,.csv"
    format-tip=".xls / .xlsx / .csv"
    :limit="3"
    drag-text="Drop report files here or click to upload"
  />
</template>

<script lang="ts" setup>
const mockUpload = () => {
  return new Promise((resolve) => {
    window.setTimeout(() => {
      resolve({
        result: '/images/figure-1.png',
      })
    }, 700)
  })
}
</script>

Behavior Notes ​

• model-value is an input prop used to initialize or externally reset the internal file list. The component does not emit update:modelValue; use on-change if you need to sync external state.
• When before-upload is not provided, VUpload validates accept, size, and max-file-name-length for you. Providing a custom before-upload replaces that built-in validation.
• Selected filenames are sanitized before upload by removing spaces and special characters from the base name while keeping the extension.
• After a file leaves the ready state, on-change receives a cloned normalized array shaped like { name, url, fileName, fileUrl }. While a newly selected file is still in ready, it receives the raw UploadFiles list.
• When cover-file is enabled, files with the same sanitized name replace older entries. If limit is 1, selecting a new file after the limit is reached replaces the current file.
• preview="download" turns preview clicks into downloads. Use download-method to override the default browser download. Other preview values currently have no built-in behavior in this wrapper.
• force-update-flie-list follows the current implementation spelling and forces model-value to overwrite an already initialized internal file list.
• When http-request is provided, it must return a Promise because VUpload chains then, catch, and finally on it.

Value Formats ​

• model-value accepts an array, a single object, or a string.
• String values are parsed as a JSON array first. If parsing fails, they are treated as a |-separated list of file URLs and converted to { fileName, fileUrl }.
• When auto-upload is true, existing records are normalized from fileName / fileUrl to the internal name / url fields used by Upload.
• When auto-upload is false and model-value is an array, the array is used directly as the internal UploadFiles list.

API ​

VUpload Attributes ​

VUpload Events ​

VUpload Slots ​

VUpload does not forward custom slots. The button trigger, drag area, and tip content are rendered internally from props.

Source ​

Docs