Upload

Upload files by clicking or dragging.

Basic Usage

The most common upload method, supporting multi-selection.

Only pdf/png files allowed, max 2MB

• yh-ui-manual.pdf
• business-report.docx
• example-image.png

FileList Data

[
  {
    "name": "yh-ui-manual.pdf",
    "status": "success",
    "uid": 1,
    "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
  },
  {
    "name": "business-report.docx",
    "status": "success",
    "uid": 3,
    "url": "data:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,UEsDBBQAAAAIA..."
  },
  {
    "name": "example-image.png",
    "status": "success",
    "uid": 2,
    "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
  }
]

Photo Wall

Suitable for avatars or product images.

• 

FileList Data

[
  {
    "name": "nature.jpeg",
    "url": "https://images.unsplash.com/photo-1472214103451-9374bd1c798e?w=200",
    "status": "success",
    "uid": 1
  }
]

Drag & Drop

Drop files here, or click to upload

FileList Data

[]

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.

FileList Data

[]

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.

Only pdf/png files allowed, max 2MB

FileList Data

[]

Image List Mode

• 

  food.jpeg

FileList Data

[
  {
    "name": "food.jpeg",
    "url": "https://images.unsplash.com/photo-1498050108023-c5249f4df085?w=200",
    "status": "success",
    "uid": 1
  }
]

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.

• yh-ui-manual.pdf
• business-report.docx
• example-image.png

Advanced Business: Validation & Compression

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

FileList Data

[]

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.

• 

  thumb-demo.jpg

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.

• Financial_Report.xlsx
• Project_Spec.pdf
• Requirement_Doc.docx
• Demo_Video.mp4
• BGM.mp3
• readme.txt
• Unknown_File.dat

• Financial_Report.xlsx
• Project_Spec.pdf
• Requirement_Doc.docx
• Demo_Video.mp4
• BGM.mp3
• readme.txt
• Unknown_File.dat

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.

• 

Nuxt.js Usage Instructions

Since the YhUpload component internally uses browser-specific APIs such as Viewer.js and FileReader, please ensure it is placed within the <ClientOnly> component when using it in a Nuxt 3 (SSR) environment, or ensure that relevant interactions are only triggered during the client-side lifecycle (e.g., onMounted).

<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) => 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' | ''	-

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[])

Theme Variables (CSS Variables)

All color variables are connected to the global theme system and support dark mode automatically:

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-dragger-hover-border	Drag area hover border color	var(--yh-color-primary)
--yh-upload-item-bg	List item background color	var(--yh-fill-color-blank)
--yh-upload-item-hover-bg	List item hover background color	var(--yh-fill-color-light)
--yh-upload-text-color	Text color	var(--yh-text-color-regular)
--yh-upload-text-secondary	Secondary text color	var(--yh-text-color-secondary)
--yh-upload-progress-bg	Progress bar background color	var(--yh-color-primary)
--yh-upload-card-radius	Photo wall card border radius	var(--yh-radius-md)