Vue Multi Uploader

A headless upload component that supports developers to custom for every project. DEMO

• Vue Multi Uploader
  • Installation
  • Getting Started
  • Usage
  • Options
    • Options Refs
  • Return Values
    • Modifiable Values
    • Readonly Values
    • Methods
  • Prepare Default Items
  • Fetch Uploaded Data And Set to Item
  • Programmatically Control
    • Adding Items
    • Stop Upload
  • Handle Errors
    • Invalid File
    • Upload Fail
  • Events
  • Pre-Built Components
    • Get Uploader Instance From Component

Installation

npm i vue-multi-uploader --save

# OR

yarn add vue-multi-uploader

Getting Started

Use bundler and Vue SFC:

<script setup lang="ts">
  import { useMultiUploader } from 'vue-multi-uploader';
</script>

Include JS file.

<script src="path/to/package/dist/vue-multi-uploader.umd.cjs"></script>

<script>
  VueMultiUploader.useMultiUploader();
</script>

ES Module

<script type="module">
  import { useMultiUploader } from 'path/to/package/dist/vue-multi-uploader.js';

  useMultiUploader();
</script>

Usage

This is a simple example of how to use the vue-multi-uploader component in a Vue 3 application. The example demonstrates how to set up a file upload interface with drag-and-drop functionality, progress indicators, and the ability to delete uploaded items.

Full example please refer to Demo.

<script setup lang="ts">
  import {
    type UploaderItem,
    useMultiUploader,
  } from 'vue-multi-uploader';
  import { ref, useTemplateRef } from 'vue';

  const dropzone = useTemplateRef('dropzone');

  const items = ref < UploaderItem[] > ([]);

  const {
    openFileSelector,
    deleteItem
  } = useMultiUploader(items, '/api/upload', {
    dropzone: dropzone,
    maxFiles: 5,
    onItemUploadSuccess(item, xhr) {
      const res = JSON.parse(xhr.responseText);
      item.url = res.url;
    },
  });

</script>

<template>
  <div class="">
    <!-- File List -->
    <ul>
      <li v-for="(item) of items" :key="item.key">
        <!-- Item title -->
        <div>
          {{ item.title }}
        </div>

        <!-- Progress -->
        <div class="progress progress-sm" style="height: 0.5rem">
          <div class="progress-bar" :style="{ width: (item.progress * 100) + '%' }"></div>
        </div>

        <!-- Delete Button-->
        <a href="#" @click.prevent="deleteItem(item)">
          Delete
        </a>
      </li>
    </ul>

    <!-- Dropzone -->
    <div ref="dropzone" class="dropzone"
      style="height: 300px; cursor: pointer;"
      @click="openFileSelector"
    >
      <div class="dropzone__content text-center">
        <span class="fa-solid fa-upload" style="font-size: 2rem"></span>
        <div>Click or drop to upload</div>
      </div>
    </div>
  </div>
</template>

Options

Every option item can be a value, Ref, computed, or function to make them reactive.

const disabledRef = ref(props.disabled);

useMultiUploader(items, '/api/upload', {
  maxFiles: 5, // Value
  maxConcurrent: () => 2, // Getter
  disabled: disabledRef, // Ref
});

Options Refs

| Name | Type | Default | Description | |------------------------|-----------------------------------------------------------------|-------------|-----------------------------------------------------------------------------------------------------------------------------------| | id | string | undefined | ID for the uploader instance, leave empty will auto generate. | | accept | string | undefined | Accepted file types for upload, separate by comma if multiple, can be mime type (image/*, text/plain) or ext name .jpg, .png. | | maxFiles | number | undefined | Maximum number of files allowed for upload. | | maxConcurrent | number | 2 | Maximum number of concurrent uploads. | | maxItemSize | number | undefined | Maximum size of a single file in bytes. | | disabled | boolean | false | Disables the uploader if set to true. | | readonly | boolean | false | Sets the uploader to read-only mode if set to true. | | dropzone | MaybeElement | undefined | Element or ElementRef to be used as the dropzone. | | onDragClass | string | h-ondrag | CSS class to apply when dragging files over the dropzone. | | autoStart | boolean | true | Automatically start uploading files when added, if set to false, you must call uploadStart() to start. | | prepareXhr | (xhr: XMLHttpRequest) => MaybePromise<XMLHttpRequest or void> | undefined | A function to configure the XMLHttpRequest object or return a new XMLHttpRequest object, can be async. | | onChange | (items: UploaderItem[]) => void | | Triggered when the uploader items change. | | onDeleteItem | (item: UploaderItem) => void | | Triggered when an item is deleted from uploader. | | onUploading | () => void | | Triggered when uploading process starts. | | onUploaded | () => void | | Triggered when uploading process completes. | | headers | Record<string, string> | | Custom headers to be sent with the upload request. | | data | Record<string, any> | | Custom data to be sent with the upload request. | | onItemUploadStart | (item: UploaderItem, xhr: XMLHttpRequest) => void | | Triggered when an individual file upload starts. | | onItemUploadSuccess | (item: UploaderItem, xhr: XMLHttpRequest) => void | | Triggered when a file uploads successfully, you can get the API return url here and set to item. | | onItemUploadFail | (item: UploaderItem, xhr: XMLHttpRequest) => void | | Triggered when a file fails to upload. | | onItemUploadEnd | (item: UploaderItem, xhr: XMLHttpRequest) => void | | Triggered when an individual file upload finishes. | | onItemUploadProgress | (item: UploaderItem, event: ProgressEvent) => void | | Triggered during upload progress of a file. | | onInvalidFile | (e: Error) => void | | Triggered when a file with an invalid type or size is selected. |

Return Values

Variables can be directly obtained by expanding the return values as follows:

const {
  id,
  accept,
  maxFiles,
  maxConcurrent,
  disabled,
  readonly,
  items,
  uploading,
  progress,
  addFiles,
  removeItem,
  clear,
  startUpload,
  eventBus,
  headers,
  data,
} = useMultiUploader(...)

Modifiable Values

| Name | Type | Description | |-----------------|----------------------------|----------------------------------------------------| | accept | Ref<string> | Accepted file types string (e.g., .jpg,.png) | | disabled | Ref<boolean> | Whether the uploader is disabled | | id | Ref<string> | Unique identifier for the uploader instance | | items | Ref<UploaderItem[]> | List of file items currently in the uploader | | maxConcurrent | Ref<number> | Maximum number of concurrent uploads | | maxFiles | Ref<number or undefined> | Maximum number of files allowed | | maxItemSize | Ref<number or undefined> | Maximum size of a single file in bytes | | readonly | Ref<boolean> | Whether the uploader is in read-only mode | | uploadUrl | Ref<string> | Target URL for uploads | | headers | Record<string, string> | Custom headers to be sent with the upload request. | | data | Record<string, any> | Custom data to be sent with the upload request. |

Readonly Values

| Name | Type | Description | |-----------------|-----------------|---------------------------------------------------------------------------------------------------------| | acceptedTypes | Ref<string[]> | Array of accepted file types | | canUpload | Ref<boolean> | Whether uploading is allowed, if is readonly or disabled or reaches max files, this will be false | | eventBus | Emitter | Custom event bus for listening and triggering events | | isReadonly | Ref<boolean> | Whether the uploader is in read-only state, this will merge disabled and readonly | | isUploading | Ref<boolean> | Whether an upload is currently in progress | | totalSize | Ref<number> | Total size of all files in the uploader |

Methods

| Name | Type | Description | |---------------------|----------------------------------------------------------------------|--------------------------------------------------------------------------| | addFile | (file: File) => UploaderItem | Add a file to the uploader | | addItem | (item: UploaderItem) => UploaderItem | Add an item to the uploader | | createItem | (file: File) => UploaderItem | Create a new item based on the file | | deleteItem | (child: UploaderItem) => void | Delete a specific file item from the uploader | | emits | (event: string, ...args: any[]) => void | Manually trigger specific events | | isImage | (filePath: string) => boolean | Determine if a file is an image based on its path | | isImageItem | (item: UploaderItem) => boolean | Determine if an item is an image based on UploaderItem | | on | (event: string, callback: (...event: any[]) => void) => () => void | Register event listeners and return a function to remove the listener | | openFileSelector | () => void | Open the file selection window | | uploadStart | () => Promise<PromiseSettledResult<UploaderItem>[]> | Start the upload process and return the result for each item | | stopItemUpload | (item: UploaderItem or XMLHttpRequest) => void | Stop the upload process for a specific item | | enqueueUploadFile | (item: UploaderItem) => Promise<UploaderItem> | Enqueue a file for upload, returns the created item or null if not added | | uploadFile | (item: UploaderItem) => Promise<UploaderItem> | Upload a single file, returns the uploaded item | | checkFile | (file: File) => void | Check if a file is valid, throw an Error if invalid |

Note you can modify some of the values in the return values, such as disabled, readonly, maxFiles etc. The change will be reflected in the uploader instance.

Prepare Default Items

If you have some exists files that you want to show in the uploader, you can prepare them in advance.

import { type UploaderItem, useMultiUploader } from 'vue-multi-uploader';

const defaultItems = ref<UploaderItem[]>([
  {
    key: '1',
    title: 'File 1',
    url: 'https://example.com/file1.jpg',

    // The original database record data can be stored in the `data` prop.
    data: {
      id: 1,
      title: 'File 1',
      // ...
    },
  },
  {
    key: '2',
    title: 'File 2',
    url: 'https://example.com/file2.jpg',

    // The original database record data can be stored in the `data` prop.
    data: {
      id: 1,
      title: 'File 1',
      // ...
    },
  },
]);

const { items, ... } = useMultiUploader(defaultItems, '/api/upload', {
  ...,
});

The UploaderItem interface is as follows:

export interface UploaderItem {
  key: string;
  url: string;
  thumbUrl?: string;
  title?: string;
  file?: File;
  data?: Record<string, any>;

  uploadState: UploadState; // enum
  progress: number;
  xhr?: XMLHttpRequest;
  error?: Error;

  [props: string]: any;
}

Fetch Uploaded Data And Set to Item

You can set the uploaded URL to the item after the upload is complete. Use the onItemUploadSuccess callback to do this.

const {
  ...
} = useMultiUploader(items, '/api/upload', {
  onItemUploadSuccess(item, xhr) {
    const res = JSON.parse(xhr.responseText);
    item.url = res.url;

    // If thumb image is smaller than the original image, you can set it to `thumbUrl`.
    item.thumbUrl = res.thumb_url;

    // If you want to store some returned data to the item, you can set it to `data` prop.
    item.data = res.data;
  },
});

Programmatically Control

Adding Items

You can add items programmatically by using the addFile or addItem method. If autoStart is set to true, the upload will start automatically after adding the item.

const {
  addFile,
  addItem,
  createItem,
} = useMultiUploader(items, '/api/upload', {
  ...
});

// Add a file
const item = addFile(file); // Return UploaderItem

// Add an item
const item = createItem(file);
addItem(item);

If autoStart is set to false, you need to call uploadStart().

const {
  addFile,
  uploadStart,
} = useMultiUploader(items, '/api/upload', {
  autoStart: false,
  ...
});

const item = addFile(file);

uploadStart();

Stop Upload

You can stop the upload process for a specific item by using the stopItemUpload method.

const {
  stopItemUpload,
} = useMultiUploader(items, '/api/upload', {
  ...
});

function clickToStop(item: UploaderItem) {
  stopItemUpload(item);

  // Or stop by xhr
  stopItemUpload(item.xhr);
}

Handle Errors

Invalid File

If the file is invalid, you can handle it in the onInvalidFile callback.

const {
  ...
} = useMultiUploader(items, '/api/upload', {
  onInvalidFile(e) {
    if (e.name === 'InvalidFileType') {
      console.error('Invalid file type:', e.message, e.file, e.accepted as string[]);
    } else if (e.name === 'InvalidFileSize') {
      console.error('Invalid file size:', e.message, e.file, e.maxSize);
    }
  },
});

Upload Fail

If the upload fails, you can handle it in the onItemUploadFail callback.

const {
  ...
} = useMultiUploader(items, '/api/upload', {
  onItemUploadFail(item, xhr) {
    console.error('Upload failed:', item.error, xhr);
  },
});

Events

You can use the on method to listen to events.

const { on } = useMultiUploader(items, '/api/upload', {});

const off = on('item-upload-success', (item, xhr) => {
  console.log('Item uploaded successfully:', item);
});

onUnmounted(() => {
  // Remember release the event listener
  off();
});

The eventBus is a dush() instance, so there are some features you can use:

const { eventBus } = useMultiUploader(items, '/api/upload', {});

eventBus.on('...', () => {...
});
eventBus.once('...', () => {...
});

The following events will match to on* callback in options:

| Event | Callback | |------------------------|------------------------| | change | onChange | | delete-item | onDeleteItem | | uploading | onUploading | | uploaded | onUploaded | | create-item | onCreateItem | | item-upload-start | onItemUploadStart | | item-upload-success | onItemUploadSuccess | | item-upload-fail | onItemUploadFail | | item-upload-end | onItemUploadEnd | | item-upload-progress | onItemUploadProgress | | invalid-file | onInvalidFile |

Pre-Built Components

There has a VueMultiUploader component that is a pre-built component for the uploader. Here is a simple example of how to use it.

<script setup lang="ts">
  import { MultiUploader, ItemCard, ItemCardPlaceholder } from 'vue-multi-uploader';
  import { ref } from 'vue';

  const items = ref([]);
  const uploadUrl = '/api/upload';
  const accept = '.jpg,.png';

  function onItemUploadSuccess(item, xhr) {
    console.log('Item uploaded successfully:', item);
  }

  function deleteItem(item) {
    // Remove the item from the list
  }
</script>
<template>
  <MultiUploader
    :items="items"
    :upload-url="uploadUrl"
    :max-files="5"
    :max-concurrent="2"
    :accept="accept"
    @item-upload-success="onItemUploadSuccess"
  >
    <template #items="{items, instance: {canUpload, openFileSelector, deleteItem}}">
      <div class="d-flex flex-wrap w-100 gap-3">
        <ItemCard v-for="(item, index) of items"
          :item
          :i="index"
          @delete="deleteItem"
        />

        <ItemCardPlaceholder
          v-if="canUpload"
          class=""
          text="Click or drop to upload"
          @click="openFileSelector"
        />
      </div>
    </template>
  </MultiUploader>
</template>

Examples please refer to Demo.

Get Uploader Instance From Component

You can get the uploader instance from the component.

<script setup lang="ts">
  import { MultiUploader } from 'vue-multi-uploader';
  import { onMounted, useTemplateRef } from 'vue';

  const uploader = useTemplateRef('uploader');

  onMounted(() => {
    const { items, uploadUrl, maxFiles } = uploader.value!.instance;
    console.log(items, uploadUrl, maxFiles);
  });
</script>
<template>
  <MultiUploader ref="uploader" ...>
    ...
  </MultiUploader>
</template>