🌏 Translated with the assistance of DeepSeek and ChatGPT

Upload

Synthetic Evolution

Basic Usage

action sets the upload address, while customRequest takes over the request entirely. The file list is rendered by UploadFileList and shows the name, the progress and the actions of every file.

Hide source code

Image Mode

Set mode to 'image' to let UploadImage render a grid of cards: images show their thumbnail and support click preview, while other files show a type icon. thumbnailType decides how the thumbnail is created, and createThumbnailUrl customizes the thumbnail address entirely.

Hide source code

Drag & Drop

With draggable on, the built-in trigger button is replaced by UploadDragger: the whole pixel dashed zone accepts dropped files and also opens the picker when clicked, and dropped files go through the same flow as picked ones. Place UploadDragger inside the trigger slot yourself when you want to decide where it sits.

Click or drag files here to upload

Hide source code

Disabled

With disabled set to true, Upload ignores picking, dropping and every action inside the list, and the built-in button, UploadDragger and the UploadFileList / UploadImage entries all render in their disabled style.

• 
  pixelium-logo.png
• uploading.svg
• pending.doc
• error.doc

Click or drag files here to upload

Hide source code

Manual Upload and Abort

With autoUpload set to false, files stay pending until submit is exposed by Upload and called to start them; failed files can be retried with retry. abort marks both the running and the queued files as failed and keeps them in the list, triggering abort instead of error, while setting abortable to false makes Upload ignore abort calls and hides the abort affordance in UploadFileList and UploadImage.

Hide source code

Picking Limits

accept limits the file types that can be picked, supporting extensions, MIME types, and the audio/*, image/*, video/* wildcards; multiple controls whether several files can be picked at once. The beforeUpload event validates a file further, and the file stays out of the list when its handler returns false.

Hide source code

Concurrency

concurrency limits how many uploads run at the same time: when several files are picked, the extra ones are queued with the queueing state and a progress of zero, starting one after another as the running uploads finish.

Hide source code

Download

When a file carries an url, UploadFileList renders its name as a download link and UploadImage shows a download affordance, while customDownload can take the download over.

• 
  pixelium-logo.png
• 
  chrome-logo.svg

Hide source code

Custom File List

fileList and defaultFileList keep the file list in controlled and uncontrolled mode respectively, and the whole list area can be replaced through the file-list slot.

Hide source code

Manual Composition

All three sub components can be placed by hand: put UploadFileList or UploadImage inside the file-list slot and UploadDragger inside the trigger slot - they still share the file list and the actions through the context provided by Upload.

Click or drag files here to upload

Hide source code

API

UploadProps

Attribute	Type	Optional	Default	Description	Version
accept	string[]	True		Limits the file types that can be picked.	0.2.1
size	'small' | 'medium' | 'large'	True	'medium'	The size of Upload.	0.2.1
mode	'file' | 'image'	True	'file'	The presentation mode of the file list.	0.2.1
thumbnailType	'objectURL' | 'dataURL'	True	'objectURL'	How the thumbnail of a file is created.	0.2.1
createThumbnailUrl	CreateThumbnailUrl	True		Customizes the thumbnail address of a file.	0.2.1
multiple	boolean	True	true	Whether several files can be picked at once.	0.2.1
draggable	boolean	True	false	Whether the built-in trigger button is replaced by UploadDragger.	0.2.1
disabled	boolean	True	false	Whether Upload is disabled.	0.2.1
abortable	boolean	True	true	Whether the running and the queued uploads can be aborted.	0.2.1
autoUpload	boolean	True	true	Whether the upload starts right after the files are picked.	0.2.1
concurrency	number	True		The maximum number of uploads running at the same time; no limit when it is not set or not greater than zero.	0.2.1
action	string	True		The address of the upload request.	0.2.1
method	string	True	'post'	The method used by the upload request.	0.2.1
name	string	True	'file'	The field name of the uploaded file in the request.	0.2.1
data	UploadData	True		The extra data attached to the upload request.	0.2.1
headers	UploadHeaders	True		The headers of the upload request.	0.2.1
withCredentials	boolean	True	false	Whether credentials are sent with a cross-origin upload.	0.2.1
responseType	XMLHttpRequestResponseType	True	'text'	The expected response type of the upload request.	0.2.1
isErrorState	(xhr: XMLHttpRequest) => boolean	True		Decides whether an upload request failed.	0.2.1
customRequest	CustomRequest	True		Takes over the upload request.	0.2.1
customDownload	CustomDownload	True		Takes over the download.	0.2.1
fileList	FileInfo[]	True		The file list in controlled mode.	0.2.1
defaultFileList	FileInfo[]	True		The initial file list in uncontrolled mode.	0.2.1
buttonProps	ButtonProps & EmitEvent<ButtonEvents> & RestAttrs	True		Properties of the internal Button.	0.2.1
uploadFileListProps	UploadFileListProps	True		Properties passed to UploadFileList, whose size still follows Upload.	0.2.1
uploadImageProps	UploadImageProps	True		Properties passed to UploadImage, whose size still follows Upload.	0.2.1
uploadDraggerProps	UploadDraggerProps	True		Properties passed to UploadDragger.	0.2.1

UploadEvents

Event	Parameter	Description	Version
update:fileList	fileList: FileInfo[]	Triggered when the file list changes.	0.2.1
beforeUpload	params: { file: File; fileList: FileInfo[] }	Triggered before a file joins the list; return a Promise<boolean | void> | boolean | void to decide the result, and the file stays out when the awaited value is false.	0.2.1
beforeRemove	params: { file: FileInfo; fileList: FileInfo[] }	Triggered before a file is removed; return a Promise<boolean | void> | boolean | void to decide the result, and the removal is cancelled when the awaited value is false.	0.2.1
change	fileList: FileInfo[], e: Event	Triggered when the file list changes (files added, removed or cleared).	0.2.1
progress	item: FileInfo, percent: number, e: ProgressEvent	Triggered when the progress of an upload changes.	0.2.1
finish	item: FileInfo, response: any, e: ProgressEvent	Triggered when a file finishes uploading.	0.2.1
error	item: FileInfo, error: any, e: ProgressEvent	Triggered when a file fails to upload.	0.2.1
abort	item: FileInfo	Triggered when a file is aborted.	0.2.1
remove	item: FileInfo, e: MouseEvent	Triggered when a file is removed.	0.2.1

UploadSlots

Slot	Parameter	Description	Version
trigger	open: () => void	The area that triggers picking files.	0.2.1
file-list	fileList: FileInfo[], remove: (id: string) => void, abort: (id?: string) => void, submit: (fileId?: string) => void, retry: (fileId?: string) => void, download: (file: FileInfo) => void	The file list area, whose scope provides the file list and the actions, and the actions run on every matching file when no file is given.	0.2.1

UploadExpose

Attribute	Type	Optional	Default	Description	Version
open	() => void	False		Opens the file picker.	0.2.1
submit	(fileId?: string) => void	False		Starts uploading the pending files, handling every pending file when none is given.	0.2.1
retry	(fileId?: string) => void	False		Retries the files that failed to upload, handling every failed file when none is given.	0.2.1
remove	(id: string) => void	False		Removes a file from the list.	0.2.1
abort	(id?: string) => void	False		Aborts the running and the queued uploads, aborting every running or queued upload when none is given.	0.2.1
clear	() => void	False		Clears the file list.	0.2.1

UploadFileListProps

Attribute	Type	Optional	Default	Description	Version
size	'small' | 'medium' | 'large'	True	'medium'	The size of UploadFileList, inheriting the size of Upload when it is not set.	0.2.1
abortable	boolean	True	true	Whether the running and the queued uploads can be aborted, showing the abort affordance only when Upload allows it as well.	0.2.1
previewable	boolean	True	true	Whether the thumbnails can be previewed by click.	0.2.1
showProgress	boolean	True	true	Whether the upload progress is shown.	0.2.1

UploadImageProps

Attribute	Type	Optional	Default	Description	Version
size	'small' | 'medium' | 'large'	True	'medium'	The size of UploadImage, inheriting the size of Upload when it is not set.	0.2.1
abortable	boolean	True	true	Whether the running and the queued uploads can be aborted, showing the abort affordance only when Upload allows it as well.	0.2.1
previewable	boolean	True	true	Whether the thumbnails can be previewed by click.	0.2.1
showProgress	boolean	True	true	Whether the upload progress is shown.	0.2.1

UploadDraggerProps

Attribute	Type	Optional	Default	Description	Version
text	string	True		The hint text of the drop zone.	0.2.1

UploadDraggerSlots

Slot	Parameter	Description	Version
default		The hint content of the drop zone.	0.2.1
icon		The icon of the drop zone.	0.2.1

FileInfo

export interface FileInfo {
	id: string
	name: string
	type?: string
	file?: File
	state: 'pending' | 'queueing' | 'uploading' | 'finished' | 'error'
	progress: number
	url?: string
	thumbnailUrl?: string
	response?: any
}

UploadData

export type UploadData =
	| Record<string, string>
	| ((params: { file: FileInfo }) => Record<string, string>)

UploadHeaders

export type UploadHeaders =
	| Record<string, string>
	| ((params: { file: FileInfo }) => Record<string, string>)

UploadPatch

export type UploadPatch = {
	url?: string
	thumbnailUrl?: string
	response?: any
}

UploadCustomRequestOptions

export interface UploadCustomRequestOptions {
	file: FileInfo
	action?: string
	withCredentials?: boolean
	data?: UploadData
	headers?: UploadHeaders
	signal: AbortSignal
	setProgress: (e: { percent: number }) => void
	setFinish: (patch?: UploadPatch) => void
	setError: (patch?: UploadPatch) => void
}

CustomRequest

export type CustomRequest = (options: UploadCustomRequestOptions) => any

CustomDownload

export type CustomDownload = (params: { file: FileInfo }) => void

CreateThumbnailUrl

export type CreateThumbnailUrl = (params: {
	file: FileInfo
}) => string | undefined | Promise<string | undefined>

EmitEvent

export type EmitEvent<T extends Record<string, any>> = {
	[K in keyof T as `on${Capitalize<K & string>}`]?: (...args: T[K]) => void
}

RestAttrs

import type { StyleValue } from 'vue'

export type VueClassValue = string | Record<string, any> | VueClassValue[]
export type VueStyleValue = StyleValue

export type RestAttrs = {
	style?: VueStyleValue | null
	class?: VueClassValue | null
	[x: string]: any
}