Van Uploader

Vant Uploader Component

Uploader component for uploading files with preview, progress, and status management.

When to Invoke

Invoke this skill when:

• User needs to implement file upload functionality
• User wants to create image upload with preview
• User needs to limit file size or count
• User wants to customize upload appearance
• User asks about upload status and progress

Features

• File Preview: Preview images and files before upload
• Multiple Upload: Support for multiple file selection
• Size Limit: Configurable maximum file size
• Count Limit: Limit number of files
• Upload Status: Show uploading, success, and failed states
• Custom Upload Area: Customizable upload button
• Before Read: Pre-processing and validation hooks
• After Read: Post-processing hooks
• Reupload: Support for re-uploading files
• Preview Cover: Custom preview overlay content

API Reference

Props

Events

Slots

Methods

Usage Examples

Basic Usage

<template>
  <van-uploader :after-read="afterRead" />
</template>

<script setup>
const afterRead = (file) => {
  console.log(file)
}
</script>

Preview File

<template>
  <van-uploader v-model="fileList" multiple />
</template>

<script setup>
import { ref } from 'vue'

const fileList = ref([
  { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg' },
  { url: 'https://cloud-image', isImage: true }
])
</script>

Upload Status

<template>
  <van-uploader v-model="fileList" :after-read="afterRead" />
</template>

<script setup>
import { ref } from 'vue'

const fileList = ref([
  {
    url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg',
    status: 'uploading',
    message: 'Uploading...'
  },
  {
    url: 'https://fastly.jsdelivr.net/npm/@vant/assets/tree.jpeg',
    status: 'failed',
    message: 'Failed'
  }
])

const afterRead = (file) => {
  file.status = 'uploading'
  file.message = 'Uploading...'

  setTimeout(() => {
    file.status = 'failed'
    file.message = 'Failed'
  }, 1000)
}
</script>

Max Count

<template>
  <van-uploader v-model="fileList" multiple :max-count="2" />
</template>

<script setup>
import { ref } from 'vue'

const fileList = ref([])
</script>

Max Size

<template>
  <van-uploader 
    multiple 
    :max-size="500 * 1024" 
    @oversize="onOversize" 
  />
</template>

<script setup>
import { showToast } from 'vant'

const => {
  console.log(file)
  showToast('File size cannot exceed 500kb')
}
</script>

Custom Size Limit by Type

<template>
  <van-uploader multiple :max-size="isOverSize" />
</template>

<script setup>
const isOverSize = (file) => {
  const maxSize = file.type === 'image/jpeg' ? 500 * 1024 : 1000 * 1024
  return file.size >= maxSize
}
</script>

Custom Upload Area

<template>
  <van-uploader>
    <van-button icon="plus" type="primary">Upload Image</van-button>
  </van-uploader>
</template>

Preview Cover

<template>
  <van-uploader v-model="fileList">
    <template #preview-cover="{ file }">
      <div class="preview-cover van-ellipsis">{{ file.name }}</div>
    </template>
  </van-uploader>
</template>

<script setup>
import { ref } from 'vue'

const fileList = ref([
  { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg', name: 'Leaf' }
])
</script>

<style scoped>
.preview-cover {
  position: absolute;
  bottom: 0;
  box-sizing: border-box;
  width: 100%;
  padding: 4px;
  color: #fff;
  font-size: 12px;
  text-align: center;
  background: rgba(0, 0, 0, 0.3);
}
</style>

Preview Size

<template>
  <van-uploader v-model="fileList" preview-size="60" />
</template>

<script setup>
import { ref } from 'vue'

const fileList = ref([
  { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg' }
])
</script>

Before Read

<template>
  <van-uploader :before-read="beforeRead" />
</template>

<script setup>
import { showToast } from 'vant'

const beforeRead = (file) => {
  if (file.type !== 'image/jpeg') {
    showToast('Please upload an image in jpg format')
    return false
  }
  return true
}

const asyncBeforeRead = (file) => {
  return new Promise((resolve, reject) => {
    if (file.type !== 'image/jpeg') {
      showToast('Please upload an image in jpg format')
      reject()
    } else {
      const img = new File(['foo'], 'bar.jpg', { type: 'image/jpeg' })
      resolve(img)
    }
  })
}
</script>

Disable Uploader

<template>
  <van-uploader disabled />
</template>

Enable Reupload

<template>
  <van-uploader v-model="fileList" reupload max-count="2" />
</template>

<script setup>
import { ref } from 'vue'

const fileList = ref([
  { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg' }
])
</script>

Complete Upload Example

<template>
  <div class="upload-page">
    <van-uploader
      v-model="fileList"
      multiple
      :max-count="5"
      :max-size="5 * 1024 * 1024"
      :after-read="afterRead"
      :before-delete="beforeDelete"
      @oversize="onOversize"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { showToast, showConfirmDialog } from 'vant'

const fileList = ref([])

const afterRead = async (file) => {
  file.status = 'uploading'
  file.message = 'Uploading...'

  try {
    await uploadFile(file.file)
    file.status = 'done'
    file.message = 'Success'
    showToast('Upload successful')
  } catch (error) {
    file.status = 'failed'
    file.message = 'Failed'
    showToast('Upload failed')
  }
}

const uploadFile = (file) => {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      resolve({ url: 'https://example.com/image.jpg' })
    }, 2000)
  })
}

const beforeDelete = async (file) => {
  try {
    await showConfirmDialog({
      title: 'Delete',
      message: 'Are you sure to delete this file?'
    })
    return true
  } catch {
    return false
  }
}

const => {
  showToast('File size cannot exceed 5MB')
}
</script>

Avatar Upload

<template>
  <div class="avatar-upload">
    <van-uploader
      v-model="avatar"
      :max-count="1"
      :after-read="afterRead"
      preview-size="100"
    >
      <template #default>
        <div class="upload-avatar">
          <van-icon name="user-o" size="40" />
          <span>Upload Avatar</span>
        </div>
      </template>
    </van-uploader>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { showToast } from 'vant'

const avatar = ref([])

const afterRead = async (file) => {
  file.status = 'uploading'
  file.message = 'Uploading...'
  
  await new Promise(resolve => setTimeout(resolve, 1500))
  
  file.status = 'done'
  showToast('Avatar uploaded')
}
</script>

<style scoped>
.avatar-upload {
  display: flex;
  justify-content: center;
  padding: 32px;
}

.upload-avatar {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  width: 100px;
  height: 100px;
  background: #f7f8fa;
  border-radius: 50%;
  color: #969799;
}

.upload-avatar span {
  margin-top: 8px;
  font-size: 12px;
}
</style>

With Form

<template>
  <van-form @submit="onSubmit">
    <van-field name="uploader" label="Images">
      <template #input>
        <van-uploader v-model="fileList" multiple :max-count="3" />
      </template>
    </van-field>
    <div style="margin: 16px;">
      <van-button round block type="primary" native-type="submit">
        Submit
      </van-button>
    </div>
  </van-form>
</template>

<script setup>
import { ref } from 'vue'
import { showToast } from 'vant'

const fileList = ref([])

const => {
  showToast(`Submitted ${fileList.value.length} files`)
}
</script>

Best Practices

1. File Validation: Use before-read for file type and size validation
2. Upload Feedback: Show upload status and progress
3. Error Handling: Handle upload failures gracefully
4. Size Limits: Set reasonable file size limits
5. Count Limits: Limit number of files for better UX
6. Preview: Enable preview for better user experience
7. Accessibility: Provide clear upload instructions
8. Mobile Optimization: Use capture attribute for camera access