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

``shell
npm i vue-multi-uploader --save

OR

yarn add vue-multi-uploader
`

Getting Started

Use bundler and Vue SFC:

`vue


`

Include JS file.

`html


`

ES Module

`html

`

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.

`html

`

Options

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

`ts
const disabledRef = ref(props.disabled);

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

$3

| 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 | 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 | | Custom headers to be sent with the upload request. |
| data | Record | | 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:

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

`

$3

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

$3

| Name | Type | Description |
|-----------------|-----------------|---------------------------------------------------------------------------------------------------------|
| acceptedTypes | Ref | Array of accepted file types |
| canUpload | Ref | 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 | Whether the uploader is in read-only state, this will merge disabled and readonly |
| isUploading | Ref | Whether an upload is currently in progress |
| totalSize | Ref | Total size of all files in the uploader |

$3

| 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[]> | 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 | Enqueue a file for upload, returns the created item or null if not added |
| uploadFile | (item: UploaderItem) => Promise | 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.

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

const defaultItems = ref([
{
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:

`ts
export interface UploaderItem {
key: string;
url: string;
thumbUrl?: string;
title?: string;
file?: File;
data?: Record;

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.

`ts
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

$3

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.

`ts
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().

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

const item = addFile(file);

uploadStart();
`

$3

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

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

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

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

`

Handle Errors

$3

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

`ts
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);
}
},
});
`

$3

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

`ts
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.

`ts
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:

`ts
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.

`vue

`

Examples please refer to Demo.

$3

You can get the uploader instance from the component.

`vue



``