Upload

Upload files by clicking or dragging.

Basic Usage

The most common upload method, supporting multi-selection.

Photo Wall

Suitable for avatars or product images.

Drag & Drop

Directory Upload

Enable folder upload via the directory attribute. Once enabled, only folders can be selected; files within the folder will be flattened and uploaded sequentially.

Manual Upload

Disable automatic upload by setting the auto-upload attribute to false, then manually trigger upload by calling the submit method of the component instance.

Image List Mode

Custom Upload

The http-request attribute allows you to completely customize the upload implementation logic, such as using your own axios instance or connecting to a specific cloud storage SDK.

Download & Custom Download

The download button can be displayed via the show-download attribute. Clicking the download button will trigger the download event.

TIP

About Download Functionality: The component has built-in mandatory download logic based on Blob. However, please note that if the file is stored on a third-party server without Cross-Origin Resource Sharing (CORS) enabled, the browser may downgrade to "Open in new window preview" mode due to security policies. It is recommended to ensure that the static resource server has the Access-Control-Allow-Origin response header configured in production environments.

Advanced Business: Validation & Compression

In actual business scenarios, we often need to check file size and type before uploading, or even compress images.

Custom Thumbnail

The thumbnail-request attribute gives you complete control over preview image generation logic. For example, performing quality compression on large images before displaying them, or returning different default placeholders based on file extensions.

Avatar Upload (Single Replacement)

A very practical case. Limit the upload quantity via limit="1" and use the exceed event to replace the old image with a new one directly for an "Avatar Upload" effect.

Photo Wall Position & Preview Download

The trigger-position attribute controls the position of the upload button relative to the list (top | bottom | left | right). In picture-card mode, after enabling show-download, a download button will also appear when hovering over the preview image.

Overwrite Previous File

By setting limit="1" and listening to the exceed event, you can achieve the effect of automatically replacing the previous file when a new file is selected.

File Type Icons

The component automatically matches corresponding icons based on file extensions (Word, Excel, PDF, video, audio, text, etc.). For unknown types, it displays an "Attachment" icon by default. You can also completely customize it via the file-icon slot.

Custom File List Slot

Use the file scoped slot to completely customize each item in the file list, satisfying more complex UI requirements.

File Preview Feature

By listening to the preview event, you can implement preview logic when clicking on a file. For image files, the component already has a built-in viewerjs preview engine.

Use in Nuxt

YhUpload can be rendered in Nuxt pages, but preview, thumbnail generation, drag-and-drop, and file reading rely on browser APIs. In SSR scenarios, keep those interactive parts inside <ClientOnly> or trigger them only after the client has mounted.

<template>
  <ClientOnly>
    <yh-upload action="/api/upload">
      <yh-button type="primary">Nuxt Upload File</yh-button>
    </yh-upload>
  </ClientOnly>
</template>

API

Props

Attribute	Description	Type	Default
v-model:file-list	Uploaded file list	UploadFile[]	[]
action	Upload target URL	string	''
method	Upload HTTP method	string	'POST'
headers	Set upload request headers	Record<string, string>	{}
data	Additional parameters with upload	Record<string, unknown>	{}
name	Upload file field name	string	'file'
multiple	Whether to support multi-selection	boolean	false
drag	Whether to enable drag-and-drop upload	boolean	false
accept	Accepted file types	string	''
showFileList	Whether to show the uploaded file list	boolean	true
limit	Maximum number of files allowed	number	-
autoUpload	Whether to upload immediately after selection	boolean	true
listType	File list display style	'text' | 'picture' | 'picture-card'	'text'
withCredentials	Support sending cookie credentials	boolean	false
httpRequest	Override default upload behavior	(options: UploadRequestOptions) => Promise<unknown> | void	-
beforeUpload	Hook before file is uploaded	(file: UploadRawFile) => boolean | Promise<boolean | Blob>	-
beforeRemove	Hook before file is removed	(file: UploadFile, fileList: UploadFile[]) => boolean | Promise<boolean>	-
disabled	Whether to disable upload	boolean	false
thumbnailRequest	Custom thumbnail generation logic	(file: UploadRawFile) => Promise<string> | string	-
maxSize	File size limit (KB)	number	-
directory	Whether to enable folder upload. Flattened files within folders will be processed.	boolean	false
showDownload	Whether to show the download button	boolean	false
triggerPosition	Trigger position relative to the list	'top' | 'bottom' | 'left' | 'right'	'top'
fileIcon	Custom file icon or icon generation function	string | ((file: UploadFile) => string)	-
crossorigin	Native attribute crossorigin	'anonymous' | 'use-credentials' | ''	-
themeOverrides	Component-level theme overrides	ComponentThemeVars	undefined

Events

Name	Description	Parameters
update:fileList	Triggered when the file list is updated	(fileList: UploadFile[])
change	Triggered when file status changes	(file: UploadFile, fileList: UploadFile[])
success	Triggered on successful upload	(response: unknown, file: UploadFile, fileList: UploadFile[])
error	Triggered on upload failure	(error: Error, file: UploadFile, fileList: UploadFile[])
progress	Triggered when upload progress changes	(event: UploadProgressEvent, file: UploadFile, fileList: UploadFile[])
remove	Triggered when a file is removed	(file: UploadFile, fileList: UploadFile[])
preview	Triggered on clicking file preview	(file: UploadFile)
download	Triggered on clicking file download	(file: UploadFile)
exceed	Triggered when selected files exceed limit	(files: File[], fileList: UploadFile[])

Slots

Name	Description	Scope
default	Content to trigger upload	-
trigger	Element to trigger selection (non-drag mode)	-
tip	Tip or description text	-
file	Custom file list item content	{ file: UploadFile }
file-icon	Custom file type icon	{ file: UploadFile }

Expose

Method	Description	Parameters
submit	Manually upload the pending file list	-
triggerInput	Manually evoke the file selection box	-
handleRemove	Manually remove a specific file	(file: UploadFile)
handlePreview	Manually trigger file preview	(file: UploadFile)
handleDownload	Manually trigger file download	(file: UploadFile)
handleFiles	Manually add and process file list	(files: File[] | FileList)

Theme Variables

YhUpload supports themeOverrides. The stylesheet directly consumes the following upload-specific CSS variables, while related colors still inherit from the shared theme token system:

Variable	Description	Default
--yh-upload-dragger-bg	Drag area background color	var(--yh-bg-color)
--yh-upload-dragger-border	Drag area border color	var(--yh-border-color-light)
--yh-upload-item-bg	File list item background color	var(--yh-fill-color-blank)
--yh-upload-progress-bg	Progress bar color	var(--yh-color-primary)
--yh-upload-error-bg	Error item background color	var(--yh-color-danger-light-9)
--yh-upload-error-hover-bg	Error item hover background color	var(--yh-color-danger-light-7)

Type Exports

Name	Description
YhUploadProps	Component props type
YhUploadEmits	Component emits type
YhUploadSlots	Component slots type
YhUploadExpose	Component expose type
YhUploadFile	Uploaded file type
YhUploadRawFile	Raw file type
YhUploadProgressEvent	Upload progress event type
YhUploadRequestOptions	Upload request options type
YhUploadStatus	Upload status union
YhUploadInstance	Component instance type