Input · Upload
File selection upload


How to import

Basic usage

The most basic usage is to place a Button in children, click on the children content (the placed Button) to activate the file selection box, and the upload will start automatically after the selection is completed

Add prompt text

Set a custom prompt text through the prompt slot Set the slot position by promptPosition, optional left, right, bottom, the default is right
When listType is picture, the reference object at promptPosition is the whole picture wall list

Click on the avatar to trigger upload

Custom upload attributes

Custom upload attributes can be added by setting data, headers

Upload file type

The type of files uploaded can be restricted through the accept attribute (the native html attribute of input).
accept supports the following two types of strings:
  • A collection of file extensions (recommended), such as .jpg, .png, etc.;
  • MIME types collection of file types, please refer to MDN document
For example, only allowing users to upload PNG and PDF files, accept can be written like this: accept ='.pdf,.png' or accept ='application/pdf,image/png' (the MIME type of PNG and PDF Connect through ,).
Upload will intercept files that do not meet the accept format internally. When files that do not meet the format requirements are intercepted, the onAcceptInvalid method (provided by v1.24) will be triggered;
accept uses the suffix to avoid the incompatibility between file.type and MIME due to different browsers or operating systems.

Upload folder

By passing in directory as true, all files in the folder can be uploaded

Select multiple files at once

You can select multiple files to upload at the same time by setting the multiple attribute.

Limit the total number of files

You can limit the maximum number of files that can be uploaded by setting the limit property When limit is 1, always replace the current one with the latest upload, and will not trigger the onExceed callback v1.5.0 takes effect
In the photo wall mode, when the number of uploaded files is equal to the limit, the upload entry will be automatically hidden

Limit upload file size

The upload file size limit can be customized through the maxSize and minSize properties, and the callback when the limit is exceeded can be set by setting onSizeError.

Custom preview logic

When listType is list, you can pass in previewFile to view the logic. For example, when you do not need to preview the image type by thumbnail, you can always return a <IconFile /> in previewFile

Custom list operation area

When listType is list, you can customize the list operation area by passing in renderFileOperation

Default file list

The uploaded files can be displayed through defaultFileList. When you need to preview the thumbnail of the default file, you can set the preview attribute of the corresponding item in defaultFileList to true

Controlled component

When fileList is passed in, it is used as a controlled component. Need to listen to the onChange callback, and pass the fileList back to Upload (note that a new array object needs to be passed in)

Photo Wall

Set listType ='picture', users can upload pictures and display thumbnails in the list
Set showPicInfo, you can view the basic information of the picture
You can customize the preview icon through renderPicPreviewIcon, onPreviewClick, when the replacement icon showReplace is displayed, the preview icon will no longer be displayed.
When you need to customize the preview/replacement function, you need to turn off the replacement function and use renderPicPreviewIcon to listen for icon click events.
onPreviewClick listens for the click event of the single image container
Set hotSpotLocation to customize the order of click hotspots, the default is at the end of the photo wall list


Manually trigger upload

uploadTrigger='custom', the upload will not be triggered automatically after the file is selected. Need to manually call the upload method on the ref to trigger

Drag and drop upload

draggable='true', you can use the drag and drop function
When the directory is true, because the browser automatically imposes restrictions, it is not allowed to select a single file when clicking upload. When dragging, we think it is more reasonable to allow folders and files to be dragged, so no additional interception processing is performed.
You can quickly set the content of the drag area through dragIcon, dragMainText, dragSubText
You can also pass in ReactNode through children to completely customize the display of the drag area
The scss style is as follows

Custom check before upload

The file status can be updated through the beforeUpload hook, which is to verify the file after selecting the file before uploading online, ({ file: FileItem, fileList: Array<FileItem> }) => beforeUploadResult | Promise | boolean During synchronization verification, a boolean (true means the verification passed, false means the verification failed, and the verification failure will prevent the file from uploading online) or an Object object. The specific structure is as follows
In the case of asynchronous verification, a Promise must be returned. Promise resolve means that the verification is passed, and reject means that the verification fails and the upload will not be triggered. Object can be passed in when resolve/reject (the structure is the same as beforeUploadResult)

Update file information after upload

The file status, verification information, and file name can be updated through the afterUpload hook. ({ response: any, file: FileItem, fileList: Array<FileItem> }) => afterUploadResult afterUpload is triggered when the upload is completed (xhr.onload) and no error occurs, it needs to return an Object object (asynchronous return is not supported), the specific structure is as follows

Custom request

When customRequest is passed in, it is equivalent to using the custom request method to replace the upload built-in xhr request, and the user needs to take over the upload behavior by himself. The file object of the current operation can be obtained in the input parameters, and the user implements the upload process by himself, and calls onProgress, onError, and onSuccess in the customRequest input parameters when appropriate to update the internal state of the Upload component customRequest contains the following input parameters

API Reference

PropertyDescriptionTypeDefault ValueVersion
accepthtml Native attribute, accept uploaded file type.
The value of accept is the MIME types string or file that you allow to select the file Suffix (.jpg, etc.)
actionFile upload address, requiredstring
afterUploadHook after the file upload, update the file status according to the returned objectfunction(auProps) => afterUploadResult1.0.0
beforeClearCall back before clearing the file, judge whether to continue removing according to the return value, return false, Promise.resolve(false), Promise.reject() will prevent removal(fileList: Array<FileItem >) => boolean | Promise1.31.0
beforeRemoveCallback before removing the file, judge whether to continue removing according to the return value, return false, Promise.resolve(false), Promise.reject() will prevent removal(file: <FileItem>, fileList: Array<FileItem >) => boolean | Promise1.31.0
beforeUploadThe hook before uploading the file, according to the return object to update the file status, control whether to uploadfunction(buProps) => beforeUploadResult | Promise | boolean1.0.0
captureThe way of media shooting in the file upload controlboolean | string | undefined
classNameclass namestring
customRequestAsynchronous request method for custom upload(object: customRequestArgs) => void1.5.0
dataAdditional parameters attached to the upload or the method to return the uploaded additional parametersobject|(file: File) => object{}
defaultFileListList of uploaded filesArray<FileItem>[]
directoryFolder type uploadbooleanfalse1.20.0
disabledWhether to disablebooleanfalse
dragIconIcon on the left side of the drag areaReactNode<IconUpload />0.22.0
dragMainTextMain text of the drag areaReactNode'Click to upload the file or drag and drop the file here'0.22.0
dragSubTextDrag area help textReactNode''0.22.0
draggableWhether to support drag and drop uploadbooleanfalse0.22.0
fileListA list of uploaded files. When this value is passed in, upload is a controlled componentArray<FileItem>1.0.0
fileNamehas the same function as name and is mainly used in Form.Upload. In order to avoid conflicts with the of Field, a renamed props is provided herestring1.0.0
headersThe headers attached to the upload or the method to return the uploaded additional headersobject|(file: File) = > object{}
hotSpotLocation照片墙点击热区的放置位置,可选值 start, endstring'end'2.5.0
itemStyleInline style of fileCardCSSProperties1.0.0
limitMaximum number of files allowed to be uploadednumber
listTypeFile list display type, optional picture, liststring'list'
maxSizeMaximum file size limit, in KBnumber
minSizeMinimum file size limit, unit KBnumber
multipleWhether to allow multiple files to be selected at a timebooleanfalse
nameFile name used when uploadingstring''
onAcceptInvalidTriggered when the received file does not conform to the accept specification (generally because the folder selects all types of files / drags and drops files that do not conform to the format)(files: File[]) => void1.24 .0
onChangeCalled when the file status changes, including upload success, failure, upload, the callback input parameter is Object, including fileList, currentFile, etc.({fileList: Array<FileItem>, currentFile?: FileItem}) = > void1.0.0
onClearCallback when click to clear() => void1.1.0
onDropTriggered when the dragged element is released on the drag area(e, files: Array<File>, fileList: Array<FileItem>) => void1.9.0
onErrorCallback when uploading error(error: Error, file: File, fileList: Array<FileItem> , xhr: XMLHttpRequest) => void
onExceedCallback when the total number of uploaded files exceeds limit(fileList:Array<FileItem>) => void
onFileChangeCallback after file selection(Array<File>) => void
onOpenFileDialogTriggered when opening the system file system file selection pop-up window() => void1.18.0
onPreviewClickCallback when the file card is clicked(fileItem: FileItem) => void1.8.0
onProgressCallback when uploading files(percent: number, file: File, fileList: Array<FileItem> ) => void
onRemoveCallback for removing files(currentFile: File, fileList:Array<FileItem>, currentFileItem: FileItem ) => void
onRetryUpload retry callback(file: <FileItem>) => void1.18.0
onSizeErrorFile size invalid callback(file:File, fileList:Array<FileItem>) => void
onSuccessCallback after successful upload(responseBody: object, file: File, fileList:Array<FileItem> ) => void
previewFileCustomize the preview logic, the content returned by this function will replace the original thumbnail(fileItem: FileItem) => ReactNode
promptCustom slot, which can be used to insert prompt text. Different from writing directly in children, the content of prompt will not trigger upload when clicked.
(In the picture wall mode, the incoming prompt is only supported after v1.3.0)
promptPositionThe position of the prompt text. When the listType is list, the reference object is the children element; when the listType is picture, the reference object is the picture list. Optional values ​​left, right, bottom
(In picture wall mode, promptPosition is only supported after v1.3.0)
renderFileItemCustom rendering of fileCard(renderProps: RenderFileItemProps) => ReactNode1.0.0
renderFileOperationCustom list item operation area(renderProps: RenderFileItemProps)=>ReactNode2.5.0
renderPicInfoCustom photo wall information, only valid in photo wall mode(renderProps: RenderFileItemProps)=>ReactNode2.2.0
renderPicPreviewIconThe preview icon displayed when customizing the photo wall hover, only valid in photo wall mode(renderProps: RenderFileItemProps)=>ReactNode2.5.0
renderThumbnailCustom picture wall thumb, only valid in photo wall mode(renderProps: RenderFileItemProps)=>ReactNode2.2.0
showClearWhen limit is not 1 and the current number of uploaded files is greater than 1, whether to show the clear buttonbooleantrue1.0.0
showPicInfoWhether to display picture information, only valid in photo wall modebooleanfalse2.2.0
showReplaceWhen the upload is successful, whether to display the replace button inside the fileCardbooleanfalse1.21.0
showRetryWhen uploading fails, whether to display the retry button inside the fileCardbooleantrue1.0.0
showUploadListWhether to display the file listbooleantrue
transformFileAfter selecting the file, the callback function before uploading the file can be used to customize the conversion processing of the file(file:File) => FileItem1.0.0
uploadTriggerTrigger upload timing, optional values ​​auto, customstring'auto'
validateMessageUpload the overall error messageReactNode1.0.0
withCredentialsWhether to bring cookie informationbooleanfalse


The Upload component is an interactive control that can trigger file selection when clicking or dragging. After the file is selected, the status will be displayed in the file list.


  • Add role="button" to clickable elements
  • Add role="list" to the file list and describe it with aria-label


FileItem Interface

uid is the unique identifier of the file, and upload update and delete logic strongly relies on this value. If the current file is selected and added by upload, uid will be automatically generated. If it is passed in by props.defaultFileList or props.fileList, it must be passed, and you need to ensure that it will not be repeated


insertUpload file, when index is passed, it will be inserted at the specified position, if not passed, it will be inserted at the end(files: Array<File>, index?: number) => void2.2.0
uploadStart upload manually, use with uploadTrigger="custom"() => void

Content Guidelines

  • Upload button
  • Help text
    • The help text is written in sentences, the first letter is capitalized, and periods may not be required
  • Error message
    • Clearly tell the user why the file cannot be uploaded, and tell the user how to upload it successfully
    • Help texts are written using sentences, capitalized
    • Concise language that users can read at a glance, such as File size must be less than 20MB, File type must be .gif, .jpg, .png or .svg

Design Tokens


  • When will the retry button appear?
    • When showRetry is true and the upload of the current file fails due to a network error, the retry button will be displayed. Other statuses such as verification failed, upload successful, etc. will not display the retry button.
  • When will the replace button appear?
    • When showReplace is true and the current file status is uploaded, the replace button will be displayed.
  • Where did Semi save the pictures?
    • Semi is not responsible for the preservation of the image, you need to customize the action when you use the Upload component. You can choose to set action as your own server address or image service address.
  • Didn’t call the XXX method after uploading the picture?
    • If you set accept, you can try to remove the accept attribute, and then see if the modified method is called. After removing it, the method is called to explain that the file type obtained by accept in the current environment does not match the set accept, and the upload behavior is terminated early. You can make a breakpoint to upload/foundation.js checkFileFormat function to see if the actual value of file.type obtained meets expectations.
About the progress bar
The progress bar indicates the upload progress. The upload progress is divided into two parts: data upload and server return. If all the data has been sent, but the server does not return a response, the progress bar will stay at 90%. The user upload is not completed. At this time, the request in the developer tool will be pending, which is normal.

© 2021 - 2022 Semi Design. All rights reserved.

京ICP备19058139号-13浙公网安备 33011002016131号

Designed & Developed with love by Douyin FE & MED