Upload

Upload the file by selecting or dragging.

When To Use

Uploading is the process of publishing information (web pages, text, pictures, video, etc.) to a remote server via a web page or upload tool.

When you need to upload one or more files.
When you need to show the process of uploading.
When you need to upload files by dragging and dropping.

Examples

Upload by clicking

Classic mode. File selection dialog pops up when upload button is clicked.

Default Files

Use defaultFileList for uploaded files when page init.

Pictures with picture-circle type

Alternative display for picture-card.

Drag and Drop

You can drag files to a specific area, to upload. Alternatively, you can also upload by selecting.

We can upload several files at once in modern browsers by giving the input the multiple attribute.

Upload manually

Upload files manually after beforeUpload returns false.

Pictures with list style

If uploaded file is a picture, the thumbnail can be shown. IE8/9 do not support local thumbnail show. Please use thumbUrl instead.

Max Count

Limit files with maxCount. Will replace current one when maxCount is 1.

Aliyun OSS

Use Aliyun OSS upload example.

Drag sorting of uploadList

By using itemRender, we can integrate upload with dnd-kit to implement drag sorting of uploadList.

Customize Progress Bar

Use progress for customize progress bar.

Avatar

Click to upload user's avatar, and validate size and format of picture with beforeUpload.

The return value of function beforeUpload can be a Promise to check asynchronously. demo

Pictures Wall

After users upload picture, the thumbnail will be shown in list. The upload button will disappear when count meets limitation.

Complete control over file list

You can gain full control over filelist by configuring fileList. You can accomplish all kinds of customized functions. The following shows two circumstances:

limit the number of uploaded files.
read from response and show file link.

Upload directory

You can select and upload a whole directory.

Upload png file only

beforeUpload only prevent upload behavior when return false or reject promise, the prevented file would still show in file list. Here is the example you can keep prevented files out of list by return UPLOAD.LIST_IGNORE.

Customize preview file

Customize local preview. Can handle with non-image format files such as video.

Transform file before request

Use beforeUpload for transform file before request such as add a watermark.

custom action icon

Use showUploadList for custom action icons of files.

Crop image before uploading

Use antd-img-crop to crop image before uploading.

API

Common props ref：Common props

Property	Description	Type	Default	Version
accept	File types that can be accepted. See input accept Attribute	string	-
action	Uploading URL	string \| (file) => Promise<string>	-
beforeUpload	Hook function which will be executed before uploading. Uploading will be stopped with `false` or a rejected Promise returned. When returned value is `Upload.LIST_IGNORE`, the list of files that have been uploaded will ignore it. Warning：this function is not supported in IE9	(file, fileList) => boolean \| Promise<File> \| `Upload.LIST_IGNORE`	-
customRequest	Override for the default xhr behavior allowing for additional customization and the ability to implement your own XMLHttpRequest	function	-
data	Uploading extra params or function which can return uploading extra params	object \| (file) => object \| Promise<object>	-
defaultFileList	Default list of files that have been uploaded	object[]	-
directory	Support upload whole directory (caniuse)	boolean	false
disabled	Disable upload button	boolean	false
fileList	List of files that have been uploaded (controlled). Here is a common issue #2423 when using it	UploadFile[]	-
headers	Set request headers, valid above IE10	object	-
iconRender	Custom show icon	(file: UploadFile, listType?: UploadListType) => ReactNode	-
isImageUrl	Customize if render <img /> in thumbnail	(file: UploadFile) => boolean	(inside implementation)
itemRender	Custom item of uploadList	(originNode: ReactElement, file: UploadFile, fileList: object[], actions: { download: function, preview: function, remove: function }) => React.ReactNode	-	4.16.0
listType	Built-in stylesheets, support for four types: `text`, `picture`, `picture-card` or `picture-circle`	string	`text`	`picture-circle`(5.2.0+)
maxCount	Limit the number of uploaded files. Will replace current one when `maxCount` is `1`	number	-	4.10.0
method	The http method of upload request	string	`post`
multiple	Whether to support selected multiple files. `IE10+` supported. You can select multiple files with CTRL holding down while multiple is set to be true	boolean	false
name	The name of uploading file	string	`file`
openFileDialogOnClick	Click open file dialog	boolean	true
previewFile	Customize preview file logic	(file: File \| Blob) => Promise<dataURL: string>	-
progress	Custom progress bar	ProgressProps (support `type="line"` only)	{ strokeWidth: 2, showInfo: false }	4.3.0
showUploadList	Whether to show default upload list, could be an object to specify `showPreviewIcon`, `showRemoveIcon`, `showDownloadIcon`, `removeIcon` and `downloadIcon` individually	boolean \| { showPreviewIcon?: boolean, showDownloadIcon?: boolean, showRemoveIcon?: boolean, previewIcon?: ReactNode \| (file: UploadFile) => ReactNode, removeIcon?: ReactNode \| (file: UploadFile) => ReactNode, downloadIcon?: ReactNode \| (file: UploadFile) => ReactNode }	true	function: 4.7.0
withCredentials	The ajax upload with cookie sent	boolean	false
onChange	A callback function, can be executed when uploading state is changing, see onChange	function	-
onDrop	A callback function executed when files are dragged and dropped into the upload area	(event: React.DragEvent) => void	-	4.16.0
onDownload	Click the method to download the file, pass the method to perform the method logic, and do not pass the default jump to the new TAB	function(file): void	(Jump to new TAB)
onPreview	A callback function, will be executed when the file link or preview icon is clicked	function(file)	-
onRemove	A callback function, will be executed when removing file button is clicked, remove event will be prevented when the return value is false or a Promise which resolve(false) or reject	function(file): boolean \| Promise	-

UploadFile

Extends File with additional props.

Property	Description	Type	Default	Version
crossOrigin	CORS settings attributes	`'anonymous'` \| `'use-credentials'` \| `''`	-	4.20.0
name	File name	string	-	-
percent	Upload progress percent	number	-	-
status	Upload status. Show different style when configured	`error` \| `success` \| `done` \| `uploading` \| `removed`	-	-
thumbUrl	Thumb image url	string	-	-
uid	unique id. Will auto-generate when not provided	string	-	-
url	Download url	string	-	-

onChange

The function will be called when uploading is in progress, completed, or failed.

When uploading state change, it returns:

{
  file: { /* ... */ },
  fileList: [ /* ... */ ],
  event: { /* ... */ },
}

file File object for the current operation.

{
   uid: 'uid',      // unique identifier, negative is recommended, to prevent interference with internally generated id
   name: 'xx.png',   // file name
   status: 'done' | 'uploading' | 'error' | 'removed', // Intercepted file by beforeUpload doesn't have a status field.
   response: '{"status": "success"}', // response from server
   linkProps: '{"download": "image"}', // additional HTML props of file link
   xhr: 'XMLHttpRequest{ ... }', // XMLHttpRequest Header
}

fileList current list of files
event response from the server, including uploading progress, supported by advanced browsers.

Design Token

Component Token

Global Token

FAQ

How do I implement upload server side?

You can consult jQuery-File-Upload about how to implement server side upload interface.
There is a mock example of express in rc-upload.

I want to display download links.

Please set property url of each item in fileList to control the content of the link.

How to use `customRequest`?

See https://github.com/react-component/upload#customrequest.

Why will the `fileList` that's in control not trigger `onChange` `status` update when the file is not in the list?

onChange will only trigger when the file is in the list, it will ignore any events removed from the list. Please note that there does exist a bug which makes an event still trigger even when the file is not in the list before 4.13.0.

Why does `onChange` sometimes return File object and other times return { originFileObj: File }?

For compatible case, we return File object when beforeUpload return false. It will merge to { originFileObj: File } in the next major version. Current version is compatible to get origin file by info.file.originFileObj. You can change this before a major release.

Why sometimes Chrome can not upload?

Chrome update will also break native upload. Please restart Chrome to finish the upload work.

Ref:

Namu Design

Upload

Namu Design

Upload

When To Use

Examples

API

UploadFile

onChange

Design Token

Component Token

Global Token

FAQ

How do I implement upload server side?

I want to display download links.

How to use `customRequest`?

Why will the `fileList` that's in control not trigger `onChange` `status` update when the file is not in the list?

Why does `onChange` sometimes return File object and other times return { originFileObj: File }?

Why sometimes Chrome can not upload?

When To Use

Examples

API

UploadFile

onChange

Design Token

Component Token

Global Token

FAQ

How do I implement upload server side?

I want to display download links.

How to use `customRequest`?

Why will the `fileList` that's in control not trigger `onChange` `status` update when the file is not in the list?

Why does `onChange` sometimes return File object and other times return { originFileObj: File }?

Why sometimes Chrome can not upload?

UploadChangelog

UploadChangelog

When To Use

Examples

API

UploadFile

onChange

Design Token

Component Token

Global Token

FAQ

How do I implement upload server side?

I want to display download links.

How to use customRequest?

Why will the fileList that's in control not trigger onChange status update when the file is not in the list?

Why does onChange sometimes return File object and other times return { originFileObj: File }?

Why sometimes Chrome can not upload?

When To Use

Examples

API

UploadFile

onChange

Design Token

Component Token

Global Token

FAQ

How do I implement upload server side?

I want to display download links.

How to use customRequest?

Why will the fileList that's in control not trigger onChange status update when the file is not in the list?

Why does onChange sometimes return File object and other times return { originFileObj: File }?

Why sometimes Chrome can not upload?

Upload

Upload

How to use `customRequest`?

Why will the `fileList` that's in control not trigger `onChange` `status` update when the file is not in the list?

Why does `onChange` sometimes return File object and other times return { originFileObj: File }?

How to use `customRequest`?

Why will the `fileList` that's in control not trigger `onChange` `status` update when the file is not in the list?

Why does `onChange` sometimes return File object and other times return { originFileObj: File }?