2016-08-25 09:46:19 +08:00
---
category: Components
2022-11-09 12:28:04 +08:00
group: Data Entry
2016-09-21 11:28:38 +08:00
title: Upload
2024-03-22 14:22:42 +08:00
description: Used to select and upload files or drag and drop files.
2022-11-30 20:14:41 +08:00
cover: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*93ymR4RD4S0AAAAAAAAAAAAADrJ8AQ/original
2023-02-09 22:17:31 +08:00
coverDark: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*l1nlSryXib8AAAAAAAAAAAAADrJ8AQ/original
2022-11-09 12:28:04 +08:00
demo:
cols: 2
2016-08-25 09:46:19 +08:00
---
2016-09-10 13:43:30 +08:00
## When To Use
2016-08-25 09:46:19 +08:00
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.
2022-11-09 12:28:04 +08:00
## Examples
2022-11-17 17:31:26 +08:00
<!-- prettier - ignore -->
2022-11-09 12:28:04 +08:00
< code src = "./demo/basic.tsx" > Upload by clicking< / code >
< code src = "./demo/avatar.tsx" > Avatar< / code >
< code src = "./demo/defaultFileList.tsx" > Default Files< / code >
< code src = "./demo/picture-card.tsx" > Pictures Wall< / code >
2023-01-31 14:31:34 +08:00
< code src = "./demo/picture-circle.tsx" > Pictures with picture-circle type< / code >
2022-11-09 12:28:04 +08:00
< code src = "./demo/fileList.tsx" > Complete control over file list< / code >
< code src = "./demo/drag.tsx" > Drag and Drop< / code >
< code src = "./demo/directory.tsx" > Upload directory< / code >
< code src = "./demo/upload-manually.tsx" > Upload manually< / code >
< code src = "./demo/upload-png-only.tsx" > Upload png file only< / code >
< code src = "./demo/picture-style.tsx" > Pictures with list style< / code >
< code src = "./demo/preview-file.tsx" > Customize preview file< / code >
< code src = "./demo/max-count.tsx" > Max Count< / code >
< code src = "./demo/transform-file.tsx" > Transform file before request< / code >
< code src = "./demo/upload-with-aliyun-oss.tsx" > Aliyun OSS< / code >
< code src = "./demo/file-type.tsx" debug > custom show icon< / code >
2024-07-26 17:45:11 +08:00
< code src = "./demo/upload-custom-action-icon.tsx" > Custom action icon and extra info< / code >
2022-11-09 12:28:04 +08:00
< code src = "./demo/drag-sorting.tsx" > Drag sorting of uploadList< / code >
< code src = "./demo/crop-image.tsx" > Crop image before uploading< / code >
< code src = "./demo/customize-progress-bar.tsx" > Customize Progress Bar< / code >
2023-05-19 11:11:31 +08:00
< code src = "./demo/component-token.tsx" debug > Component Token< / code >
2023-11-08 20:43:18 +08:00
< code src = "./demo/debug-disabled.tsx" debug > Debug Disabled Styles< / code >
2022-11-09 12:28:04 +08:00
2016-08-25 09:46:19 +08:00
## API
2023-08-08 18:27:48 +08:00
Common props ref：
2019-05-06 12:04:39 +08:00
| Property | Description | Type | Default | Version |
2019-05-07 14:57:32 +08:00
| --- | --- | --- | --- | --- |
| accept | File types that can be accepted. See [input accept Attribute ](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept ) | string | - | |
2020-12-15 15:56:35 +08:00
| action | Uploading URL | string \| (file) => Promise< string> | - | |
2021-03-15 18:20:36 +08:00
| 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： | (file, fileList) => boolean \| Promise< File> \| `Upload.LIST_IGNORE` | - | |
2023-05-17 18:30:01 +08:00
| customRequest | Override for the default xhr behavior allowing for additional customization and the ability to implement your own XMLHttpRequest | function | - | |
2020-07-01 20:18:48 +08:00
| 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\[] | - | |
2020-10-21 10:33:43 +08:00
| directory | Support upload whole directory ([caniuse](https://caniuse.com/#feat=input-file-directory)) | boolean | false | |
2023-11-08 20:43:18 +08:00
| disabled | Disable upload button | boolean | false | When customizing Upload children, please pass the disabled attribute to the child node at the same time to ensure the disabled rendering effect is consistent. |
2022-12-22 14:12:26 +08:00
| fileList | List of files that have been uploaded (controlled). Here is a common issue [#2423 ](https://github.com/ant-design/ant-design/issues/2423 ) when using it | [UploadFile ](#uploadfile )\[] | - | |
2020-07-01 20:18:48 +08:00
| headers | Set request headers, valid above IE10 | object | - | |
2020-10-21 10:33:43 +08:00
| iconRender | Custom show icon | (file: UploadFile, listType?: UploadListType) => ReactNode | - | |
| isImageUrl | Customize if render < img /> in thumbnail | (file: UploadFile) => boolean | [(inside implementation) ](https://github.com/ant-design/ant-design/blob/4ad5830eecfb87471cd8ac588c5d992862b70770/components/upload/utils.tsx#L47-L68 ) | |
2021-05-06 14:12:26 +08:00
| itemRender | Custom item of uploadList | (originNode: ReactElement, file: UploadFile, fileList: object\[], actions: { download: function, preview: function, remove: function }) => React.ReactNode | - | 4.16.0 |
2023-02-13 10:21:45 +08:00
| listType | Built-in stylesheets, support for four types: `text` , `picture` , `picture-card` or `picture-circle` | string | `text` | `picture-circle` (5.2.0+) |
2021-03-14 00:10:54 +08:00
| maxCount | Limit the number of uploaded files. Will replace current one when `maxCount` is `1` | number | - | 4.10.0 |
2020-10-21 10:33:43 +08:00
| method | The http method of upload request | string | `post` | |
2023-05-17 18:30:01 +08:00
| 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 | |
2020-05-26 22:29:04 +08:00
| name | The name of uploading file | string | `file` | |
2020-10-21 10:33:43 +08:00
| openFileDialogOnClick | Click open file dialog | boolean | true | |
2020-07-01 20:18:48 +08:00
| previewFile | Customize preview file logic | (file: File \| Blob) => Promise< dataURL: string> | - | |
2022-12-22 14:12:26 +08:00
| progress | Custom progress bar | [ProgressProps ](/components/progress/#api ) (support `type="line"` only) | { strokeWidth: 2, showInfo: false } | 4.3.0 |
2024-08-07 11:42:33 +08:00
| showUploadList | Whether to show default upload list, could be an object to specify `extra` , `showPreviewIcon` , `showRemoveIcon` , `showDownloadIcon` , `removeIcon` and `downloadIcon` individually | boolean \| { extra?: ReactNode \| (file: UploadFile) => ReactNode, showPreviewIcon?: boolean \| (file: UploadFile) => boolean, showDownloadIcon?: boolean \| (file: UploadFile) => boolean, showRemoveIcon?: boolean \| (file: UploadFile) => boolean, previewIcon?: ReactNode \| (file: UploadFile) => ReactNode, removeIcon?: ReactNode \| (file: UploadFile) => ReactNode, downloadIcon?: ReactNode \| (file: UploadFile) => ReactNode } | true | `extra` : 5.20.0, `showPreviewIcon` function: 5.21.0, `showRemoveIcon` function: 5.21.0, `showDownloadIcon` function: 5.21.0 |
2020-07-01 20:18:48 +08:00
| withCredentials | The ajax upload with cookie sent | boolean | false | |
2023-08-29 18:47:41 +08:00
| onChange | A callback function, can be executed when uploading state is changing. It will trigger by every uploading phase. see [onChange ](#onchange ) | function | - | |
2023-05-17 18:30:01 +08:00
| 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 | - | |
2016-08-25 09:46:19 +08:00
2021-01-13 14:31:49 +08:00
### UploadFile
Extends File with additional props.
2022-04-18 11:16:23 +08:00
| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| crossOrigin | CORS settings attributes | `'anonymous'` \| `'use-credentials'` \| `''` | - | 4.20.0 |
| name | File name | string | - | - |
| percent | Upload progress percent | number | - | - |
2023-08-28 19:38:03 +08:00
| status | Upload status. Show different style when configured | `error` \| `done` \| `uploading` \| `removed` | - | - |
2022-04-18 11:16:23 +08:00
| thumbUrl | Thumb image url | string | - | - |
2023-05-17 18:30:01 +08:00
| uid | unique id. Will auto-generate when not provided | string | - | - |
2022-04-18 11:16:23 +08:00
| url | Download url | string | - | - |
2021-01-13 14:31:49 +08:00
2016-08-25 09:46:19 +08:00
### onChange
2023-08-29 18:47:41 +08:00
> 💡 The function will be called when uploading is in progress, completed, or failed.
2016-08-25 09:46:19 +08:00
When uploading state change, it returns:
2023-08-15 15:13:04 +08:00
```jsx
2016-08-25 09:46:19 +08:00
{
file: { /* ... */ },
fileList: [ /* ... */ ],
event: { /* ... */ },
}
```
1. `file` File object for the current operation.
2023-08-15 15:13:04 +08:00
```jsx
2016-08-25 09:46:19 +08:00
{
2023-05-17 18:30:01 +08:00
uid: 'uid', // unique identifier, negative is recommended, to prevent interference with internally generated id
2019-11-04 10:44:43 +08:00
name: 'xx.png', // file name
2023-08-15 15:13:04 +08:00
status: 'done' | 'uploading' | 'error' | 'removed', // Intercepted file by beforeUpload doesn't have a status field.
2017-10-09 13:23:20 +08:00
response: '{"status": "success"}', // response from server
2023-05-17 18:30:01 +08:00
linkProps: '{"download": "image"}', // additional HTML props of file link
2019-11-04 10:44:43 +08:00
xhr: 'XMLHttpRequest{ ... }', // XMLHttpRequest Header
2016-08-25 09:46:19 +08:00
}
```
2016-09-18 11:08:54 +08:00
2016-08-25 09:46:19 +08:00
2. `fileList` current list of files
2020-10-21 10:33:43 +08:00
2023-05-17 18:30:01 +08:00
3. `event` response from the server, including uploading progress, supported by advanced browsers.
2016-08-25 09:46:19 +08:00
2023-04-11 10:25:24 +08:00
## Design Token
< ComponentTokenTable component = "Upload" > < / ComponentTokenTable >
2019-01-04 11:13:55 +08:00
## FAQ
2022-01-24 10:51:45 +08:00
### How do I implement upload server side?
2019-01-04 11:13:55 +08:00
- You can consult [jQuery-File-Upload ](https://github.com/blueimp/jQuery-File-Upload/wiki#server-side ) about how to implement server side upload interface.
2024-05-19 15:57:47 +08:00
- There is a mock example of [express ](https://github.com/react-component/upload/blob/211979fdaa2c7896b6496df7061a0cfc0fc5434e/server.js ) in rc-upload.
2019-01-04 11:13:55 +08:00
### I want to display download links.
2016-08-25 09:46:19 +08:00
2023-05-17 18:30:01 +08:00
Please set property `url` of each item in `fileList` to control the content of the link.
2016-08-25 09:46:19 +08:00
2019-01-04 11:13:55 +08:00
### How to use `customRequest`?
2016-10-31 13:36:40 +08:00
2019-01-04 11:13:55 +08:00
See < https: / / github . com / react-component / upload # customrequest > .
2021-03-09 14:22:03 +08:00
2022-01-24 10:51:45 +08:00
### Why will the `fileList` that's in control not trigger `onChange` `status` update when the file is not in the list?
2021-03-09 14:22:03 +08:00
2022-01-24 10:51:45 +08:00
`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` .
2021-03-13 23:46:32 +08:00
2022-01-24 10:51:45 +08:00
### Why does `onChange` sometimes return File object and other times return { originFileObj: File }?
2021-03-13 23:46:32 +08:00
2023-05-17 18:30:01 +08:00
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.
2022-04-12 10:58:51 +08:00
2023-05-17 18:30:01 +08:00
### Why sometimes Chrome can not upload?
2022-04-12 10:58:51 +08:00
2024-03-22 16:38:59 +08:00
Chrome update will also break native upload. Please restart Chrome to finish the upload job.
2023-08-15 15:13:04 +08:00
Ref:
2022-04-12 14:19:32 +08:00
2024-03-22 16:38:59 +08:00
- [#48007 ](https://github.com/ant-design/ant-design/issues/48007 )
2022-04-12 14:19:32 +08:00
- [#32672 ](https://github.com/ant-design/ant-design/issues/32672 )
- [#32913 ](https://github.com/ant-design/ant-design/issues/32913 )
- [#33988 ](https://github.com/ant-design/ant-design/issues/33988 )
2023-09-25 16:58:04 +08:00
### Can still select files when uploading a folder in Safari?
Inside the upload component, we use the `directory` and `webkitdirectory` properties to control only directories can be selected. However, in Safari's implementation it doesn't seem to work. See [here ](https://stackoverflow.com/q/55649945/3040605 ). Please try passing an additional `accept` attribute that cannot match any files. For example:
```jsx
accept: `.${'n'.repeat(100)}` ;
```
