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.

• bigin-ui-logo.svg
  press delete to remove
• bigin-ui-logo2.svg
  press delete to remove

---

<template>
  <b-upload
    v-model:file-list="fileList"
    action="https://httpbin.org/post"
    multiple
    :on-preview="handlePreview"
    :on-remove="handleRemove"
    :before-remove="beforeRemove"
    :limit="3"
    :on-exceed="handleExceed"
  >
    <b-button primary small>Click to upload</b-button>
    <template #tip>
      <span>jpg/png files with a size less than 500KB.</span>
    </template>
  </b-upload>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
import { BMessage, BMessageBox } from 'bigin-ui'
import type { UploadProps, UploadUserFile } from 'bigin-ui'

const fileList = ref<UploadUserFile[]>([
  {
    name: 'bigin-ui-logo.svg',
    url: 'https://bigin-ui.org/images/bigin-ui-logo.svg',
  },
  {
    name: 'bigin-ui-logo2.svg',
    url: 'https://bigin-ui.org/images/bigin-ui-logo2.svg',
  },
])

const handleRemove: UploadProps['onRemove'] = (file, uploadFiles) => {
  // eslint-disable-next-line no-console
  console.log(file, uploadFiles)
}

const handlePreview: UploadProps['onPreview'] = (uploadFile) => {
  // eslint-disable-next-line no-console
  console.log(uploadFile)
}

const handleExceed: UploadProps['onExceed'] = (files, uploadFiles) => {
  BMessage.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, uploadFiles) => {
  return BMessageBox.confirm(
    `Cancel the transfert of ${uploadFile.name} ?`
  ).then(
    () => true,
    () => false
  )
}
</script>

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

---

<template>
  <b-upload
    ref="upload"
    class="upload-demo"
    action="https://httpbin.org/post"
    :limit="1"
    :on-exceed="handleExceed"
    :auto-upload="false"
  >
    <template #trigger>
      <b-button primary small>select file</b-button>
    </template>
    <b-button class="ml-3" small @click="submitUpload">
      upload to server
    </b-button>
    <template #tip>
      <div class="text-sm">limit 1 file, new file will cover the old file</div>
    </template>
  </b-upload>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { genFileId } from 'bigin-ui'
import type { UploadInstance, UploadProps, UploadRawFile } from 'bigin-ui'

const upload = ref<UploadInstance>()

const handleExceed: UploadProps['onExceed'] = (files) => {
  upload.value!.clearFiles()
  const file = files[0] as UploadRawFile
  file.uid = genFileId()
  upload.value!.handleStart(file)
}

const submitUpload = () => {
  upload.value!.submit()
}
</script>

User Avatar

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

---

<template>
  <b-upload
    class="avatar-uploader"
    action="https://httpbin.org/post"
    :show-file-list="false"
    :on-success="handleAvatarSuccess"
    :before-upload="beforeAvatarUpload"
  >
    <img v-if="imageUrl" :src="imageUrl" class="avatar" />
    <b-icon v-else class="avatar-uploader-icon"><ControlPlus /></b-icon>
  </b-upload>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { BMessage } from 'bigin-ui'
import { ControlPlus } from '@bigin/icons-vue'

import type { UploadProps } from 'bigin-ui'

const imageUrl = ref('')

const handleAvatarSuccess: UploadProps['onSuccess'] = (
  response,
  uploadFile
) => {
  imageUrl.value = URL.createObjectURL(uploadFile.raw!)
}

const beforeAvatarUpload: UploadProps['beforeUpload'] = (rawFile) => {
  if (rawFile.type !== 'image/jpeg') {
    BMessage.error('Avatar picture must be JPG format!')
    return false
  } else if (rawFile.size / 1024 / 1024 > 2) {
    BMessage.error('Avatar picture size can not exceed 2MB!')
    return false
  }
  return true
}
</script>

Photo Wall

Use list-type to change the fileList style.

• press delete to remove
• press delete to remove
• press delete to remove
• press delete to remove
• press delete to remove
• press delete to remove
• press delete to remove
• press delete to remove

---

<template>
  <b-upload
    v-model:file-list="fileList"
    action="https://httpbin.org/post"
    list-type="picture-card"
    :on-preview="handlePictureCardPreview"
    :on-remove="handleRemove"
  >
    <b-icon><ControlPlus /></b-icon>
  </b-upload>

  <b-dialog v-model="dialogVisible">
    <img class="w-full rd-sm" :src="dialogImageUrl" alt="Preview Image" />
  </b-dialog>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { ControlPlus } from '@bigin/icons-vue'

import type { UploadProps, UploadUserFile } from 'bigin-ui'

const fileList = ref<UploadUserFile[]>([
  {
    name: 'food.jpeg',
    url: 'https://images.unsplash.com/photo-1577879992564-abe74615967b?w=1600',
  },
  {
    name: 'plant-1.png',
    url: 'https://images.unsplash.com/photo-1579436938466-92a9ba75812f?w=1600',
  },
  {
    name: 'food.jpeg',
    url: 'https://images.unsplash.com/photo-1577879992564-abe74615967b?w=1600',
  },
  {
    name: 'plant-2.png',
    url: 'https://images.unsplash.com/photo-1541231587586-eaf981ae5fff?w=1600',
  },
  {
    name: 'food.jpeg',
    url: 'https://images.unsplash.com/photo-1577879992564-abe74615967b?w=1600',
  },
  {
    name: 'figure-1.png',
    url: 'https://images.unsplash.com/photo-1531465541337-979a89d707f0?w=1600',
  },
  {
    name: 'food.jpeg',
    url: 'https://images.unsplash.com/photo-1577879992564-abe74615967b?w=1600',
  },
  {
    name: 'figure-2.png',
    url: 'https://images.unsplash.com/photo-1515056849885-4e4aff862369?w=1600',
  },
])

const dialogImageUrl = ref('')
const dialogVisible = ref(false)

const handleRemove: UploadProps['onRemove'] = (uploadFile, uploadFiles) => {
  // eslint-disable-next-line no-console
  console.log(uploadFile, uploadFiles)
}

const handlePictureCardPreview: UploadProps['onPreview'] = (uploadFile) => {
  dialogImageUrl.value = uploadFile.url!
  dialogVisible.value = true
}
</script>

Custom Thumbnail

Use scoped-slot to change default thumbnail template.

---

<template>
  <b-upload action="#" list-type="picture-card" :auto-upload="false">
    <b-icon><ControlPlus /></b-icon>

    <template #file="{ file }">
      <div class="w-full">
        <img class="b-upload-list__item-thumbnail" :src="file.url" alt="" />
        <span class="b-upload-list__item-actions">
          <span
            class="b-upload-list__item-preview"
            @click="handlePictureCardPreview(file)"
          >
            <b-icon><zoom-in /></b-icon>
          </span>
          <span
            v-if="!disabled"
            class="b-upload-list__item-delete"
            @click="handleDownload(file)"
          >
            <b-icon><Download /></b-icon>
          </span>
          <span
            v-if="!disabled"
            class="b-upload-list__item-delete"
            @click="handleRemove(file)"
          >
            <b-icon><Delete /></b-icon>
          </span>
        </span>
      </div>
    </template>
  </b-upload>

  <b-dialog v-model="dialogVisible">
    <img class="w-full rd-sm" :src="dialogImageUrl" alt="Preview Image" />
  </b-dialog>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
import { ControlPlus, Delete, Download, ZoomIn } from '@bigin/icons-vue'

import type { UploadFile } from 'bigin-ui'

const dialogImageUrl = ref('')
const dialogVisible = ref(false)
const disabled = ref(false)

const handleRemove = (file: UploadFile) => {
  // eslint-disable-next-line no-console
  console.log(file)
}

const handlePictureCardPreview = (file: UploadFile) => {
  dialogImageUrl.value = file.url!
  dialogVisible.value = true
}

const handleDownload = (file: UploadFile) => {
  // eslint-disable-next-line no-console
  console.log(file)
}
</script>

File List with Thumbnail

jpg/png files with a size less than 500kb

• 
  food.jpeg
  press delete to remove
• 
  food2.jpeg
  press delete to remove

---

<template>
  <b-upload
    v-model:file-list="fileList"
    action="https://httpbin.org/post"
    :on-preview="handlePreview"
    :on-remove="handleRemove"
    list-type="picture"
  >
    <b-button primary small>Click to upload</b-button>
    <template #tip>
      <div class="b-upload__tip">jpg/png files with a size less than 500kb</div>
    </template>
  </b-upload>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

import type { UploadProps, UploadUserFile } from 'bigin-ui'

const fileList = ref<UploadUserFile[]>([
  {
    name: 'food.jpeg',
    url: 'https://images.unsplash.com/photo-1577879992564-abe74615967b?w=1600',
  },
  {
    name: 'food2.jpeg',
    url: 'https://images.unsplash.com/photo-1577879992564-abe74615967b?w=1600',
  },
])

const handleRemove: UploadProps['onRemove'] = (uploadFile, uploadFiles) => {
  // eslint-disable-next-line no-console
  console.log(uploadFile, uploadFiles)
}

const handlePreview: UploadProps['onPreview'] = (file) => {
  // eslint-disable-next-line no-console
  console.log(file)
}
</script>

File List Control

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

jpg/png files with a size less than 500kb

• food.jpeg
  press delete to remove
• food2.jpeg
  press delete to remove

---

<template>
  <b-upload
    v-model:file-list="fileList"
    class="upload-demo"
    action="https://httpbin.org/post"
    :on-change="handleChange"
  >
    <b-button primary small>Click to upload</b-button>
    <template #tip>
      <span>jpg/png files with a size less than 500kb</span>
    </template>
  </b-upload>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

import type { UploadProps, UploadUserFile } from 'bigin-ui'

const fileList = ref<UploadUserFile[]>([
  {
    name: 'food.jpeg',
    url: 'https://images.unsplash.com/photo-1577879992564-abe74615967b?w=1600',
  },
  {
    name: 'food2.jpeg',
    url: 'https://images.unsplash.com/photo-1577879992564-abe74615967b?w=1600',
  },
])

const handleChange: UploadProps['onChange'] = (uploadFile, uploadFiles) => {
  fileList.value = fileList.value.slice(-3)
}
</script>

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

---

<template>
  <b-upload drag action="https://httpbin.org/post" multiple>
    <b-icon class="b-icon--upload"><Upload /></b-icon>
    <div class="b-upload__text">Drop file here or <em>click to upload</em></div>
    <template #tip>
      <span>jpg/png files with a size less than 500kb</span>
    </template>
  </b-upload>
</template>

<script setup lang="ts">
import { Upload } from '@bigin/icons-vue'
</script>

Manual Upload

jpg/png files with a size less than 500kb

---

<template>
  <b-upload
    ref="uploadRef"
    class="upload-demo"
    action="https://httpbin.org/post"
    :auto-upload="false"
  >
    <template #trigger>
      <b-button primary small>select file</b-button>
    </template>

    <b-button class="ml-3" small @click="submitUpload">
      upload to server
    </b-button>

    <template #tip>
      <div class="b-upload__tip">jpg/png files with a size less than 500kb</div>
    </template>
  </b-upload>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
import type { UploadInstance } from 'bigin-ui'

const uploadRef = ref<UploadInstance>()

const submitUpload = () => {
  uploadRef.value!.submit()
}
</script>

Attributes

Name	Description	Type	Default	Required
action	request URL.	string	—	Yes
headers	request headers.	Headers | Record<string, any>	—	No
method	set upload request method.	string	post	No
multiple	whether uploading multiple files is permitted.	boolean	false	No
data	additions options of request.	Record<string, any>	—	No
name	key name for uploaded file.	string	file	No
with-credentials	whether cookies are sent.	boolean	false	No
show-file-list	whether to show the uploaded file list.	boolean	true	No
drag	whether to activate drag and drop mode.	boolean	false	No
accept	accepted file types, will not work when thumbnail-mode === true.	string	—	No
on-preview	hook function when clicking the uploaded files.	(uploadFile: UploadFile) => void	—	No
on-remove	hook function when files are removed.	(uploadFile: UploadFile, uploadFiles: UploadFiles) => void	—	No
on-success	hook function when uploaded successfully.	(response: any, uploadFile: UploadFile, uploadFiles: UploadFiles) => void	—	No
on-error	hook function when some errors occurs.	(error: Error, uploadFile: UploadFile, uploadFiles: UploadFiles) => void	—	No
on-progress	hook function when some progress occurs.	(evt: UploadProgressEvent, uploadFile: UploadFile, uploadFiles: UploadFiles) => void	—	No
on-change	hook function when select file or upload file success or upload file fail.	(uploadFile: UploadFile, uploadFiles: UploadFiles) => void	—	No
on-exceed	hook function when limit is exceeded.	(files: File[], uploadFiles: UploadFiles) => void	—	No
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.	(rawFile: UploadRawFile) => Awaitable<void | undefined | null | boolean | File | Blob>	—	No
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.	(uploadFile: UploadFile, uploadFiles: UploadFiles) => Awaitable<boolean>	—	No
file-list / v-model:file-list	default uploaded files.	UploadUserFile[]	[]	No
list-type	type of file list.	text | picture | picture-card	text	No
auto-upload	whether to auto upload file.	boolean	true	No
http-request	override default xhr behavior, allowing you to implement your own upload-file's request.	(options: UploadRequestOptions) => XMLHttpRequest | Promise<unknown>	—	No
disabled	whether to disable upload.	boolean	false	No
limit	maximum number of uploads allowed.	number	—	No

Slots

Name	Description	Scope
default	customize default content.	-
trigger	content which triggers file dialog.	-
tip	content of tips.	-
file	content of thumbnail template.	{ file: UploadFile }

Exposes

Name	Description	Type
abort	cancel upload request.	(file: UploadFile) => void
submit	upload the file list manually.	() => void
clearFiles	clear the file list (this method is not supported in the before-upload hook).	(status?: Array<"ready" | "uploading" | "success" | "fail">) => void
handleStart	select the file manually.	(rawFile: UploadRawFile) => void
handleRemove	remove the file manually.	(file: UploadFile | UploadRawFile, rawFile?: UploadRawFile) => void