logoAnt Design

⌘ K
  • Design
  • Development
  • Components
  • Blog
  • Resources
5.25.1
  • Components Overview
  • General
    • Button
    • FloatButton
      5.0.0
    • Icon
    • Typography
  • Layout
    • Divider
    • Flex
      5.10.0
    • Grid
    • Layout
    • Space
    • Splitter
      5.21.0
  • Navigation
    • Anchor
    • Breadcrumb
    • Dropdown
    • Menu
    • Pagination
    • Steps
    • Tabs
  • Data Entry
    • AutoComplete
    • Cascader
    • Checkbox
    • ColorPicker
      5.5.0
    • DatePicker
    • Form
    • Input
    • InputNumber
    • Mentions
    • Radio
    • Rate
    • Select
    • Slider
    • Switch
    • TimePicker
    • Transfer
    • TreeSelect
    • Upload
  • Data Display
    • Avatar
    • Badge
    • Calendar
    • Card
    • Carousel
    • Collapse
    • Descriptions
    • Empty
    • Image
    • List
    • Popover
    • QRCode
      5.1.0
    • Segmented
    • Statistic
    • Table
    • Tag
    • Timeline
    • Tooltip
    • Tour
      5.0.0
    • Tree
  • Feedback
    • Alert
    • Drawer
    • Message
    • Modal
    • Notification
    • Popconfirm
    • Progress
    • Result
    • Skeleton
    • Spin
    • Watermark
      5.1.0
  • Other
    • Affix
    • App
      5.1.0
    • ConfigProvider
    • Util
      5.13.0

Upload

Used to select and upload files or drag and drop files.
Importimport { Upload } from "antd";
Sourcecomponents/upload
Docs
Edit this pageChangelog

Resources

Ant Design X
Ant Design Charts
Ant Design Pro
Pro Components
Ant Design Mobile
Ant Design Mini
Ant Design Web3
Ant Design Landing-Landing Templates
Scaffolds-Scaffold Market
Umi-React Application Framework
dumi-Component doc generator
qiankun-Micro-Frontends Framework
Ant Motion-Motion Solution
China Mirror 🇨🇳

Community

Awesome Ant Design
Medium
Twitter
yuque logoAnt Design in YuQue
Ant Design in Zhihu
Experience Cloud Blog
seeconf logoSEE Conf-Experience Tech Conference

Help

GitHub
Change Log
FAQ
Bug Report
Issues
Discussions
StackOverflow
SegmentFault

Ant XTech logoMore Products

yuque logoYuQue-Document Collaboration Platform
AntV logoAntV-Data Visualization
Egg logoEgg-Enterprise Node.js Framework
Kitchen logoKitchen-Sketch Toolkit
Galacean logoGalacean-Interactive Graphics Solution
xtech logoAnt Financial Experience Tech
Theme Editor
Made with ❤ by
Ant Group and Ant Design Community
loading

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

<code src="./demo/paste.tsx" version="5.25.0"">Paste

API

Common props ref:Common props

PropertyDescriptionTypeDefaultVersion
acceptFile types that can be accepted. See input accept Attributestring-
actionUploading URLstring | (file) => Promise<string>-
beforeUploadHook 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-
customRequestOverride for the default xhr behavior allowing for additional customization and the ability to implement your own XMLHttpRequestfunction-
dataUploading extra params or function which can return uploading extra paramsobject | (file) => object | Promise<object>-
defaultFileListDefault list of files that have been uploadedobject[]-
directorySupport upload whole directory (caniuse)booleanfalse
disabledDisable upload buttonbooleanfalseWhen customizing Upload children, please pass the disabled attribute to the child node at the same time to ensure the disabled rendering effect is consistent.
fileListList of files that have been uploaded (controlled). Here is a common issue #2423 when using itUploadFile[]-
headersSet request headers, valid above IE10object-
iconRenderCustom show icon(file: UploadFile, listType?: UploadListType) => ReactNode-
isImageUrlCustomize if render <img /> in thumbnail(file: UploadFile) => boolean(inside implementation)
itemRenderCustom item of uploadList(originNode: ReactElement, file: UploadFile, fileList: object[], actions: { download: function, preview: function, remove: function }) => React.ReactNode-4.16.0
listTypeBuilt-in stylesheets, support for four types: text, picture, picture-card or picture-circlestringtextpicture-circle(5.2.0+)
maxCountLimit the number of uploaded files. Will replace current one when maxCount is 1number-4.10.0
methodThe http method of upload requeststringpost
multipleWhether to support selected multiple files. IE10+ supported. You can select multiple files with CTRL holding down while multiple is set to be truebooleanfalse
nameThe name of uploading filestringfile
openFileDialogOnClickClick open file dialogbooleantrue
pastableSupport paste filebooleanfalse5.25.0
previewFileCustomize preview file logic(file: File | Blob) => Promise<dataURL: string>-
progressCustom progress barProgressProps (support type="line" only){ strokeWidth: 2, showInfo: false }4.3.0
showUploadListWhether to show default upload list, could be an object to specify extra, showPreviewIcon, showRemoveIcon, showDownloadIcon, removeIcon and downloadIcon individuallyboolean | { 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 }trueextra: 5.20.0, showPreviewIcon function: 5.21.0, showRemoveIcon function: 5.21.0, showDownloadIcon function: 5.21.0
withCredentialsThe ajax upload with cookie sentbooleanfalse
onChangeA callback function, can be executed when uploading state is changing. It will trigger by every uploading phase. see onChangefunction-
onDropA callback function executed when files are dragged and dropped into the upload area(event: React.DragEvent) => void-4.16.0
onDownloadClick the method to download the file, pass the method to perform the method logic, and do not pass the default jump to the new TABfunction(file): void(Jump to new TAB)
onPreviewA callback function, will be executed when the file link or preview icon is clickedfunction(file)-
onRemoveA 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 rejectfunction(file): boolean | Promise-

UploadFile

Extends File with additional props.

PropertyDescriptionTypeDefaultVersion
crossOriginCORS settings attributes'anonymous' | 'use-credentials' | ''-4.20.0
nameFile namestring--
percentUpload progress percentnumber--
statusUpload status. Show different style when configurederror | done | uploading | removed--
thumbUrlThumb image urlstring--
uidunique id. Will auto-generate when not providedstring--
urlDownload urlstring--

onChange

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

When uploading state change, it returns:

jsx
{
file: { /* ... */ },
fileList: [ /* ... */ ],
event: { /* ... */ },
}
  1. file File object for the current operation.

    jsx
    {
    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
    }
  2. fileList current list of files

  3. event response from the server, including uploading progress, supported by advanced browsers.

Design Token

Component TokenHow to use?
Token NameDescriptionTypeDefault Value
actionsColorAction button colorstringrgba(0,0,0,0.45)
Global TokenHow to use?

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 job.

click restart button on Chrome

Ref:

  • #48007
  • #32672
  • #32913
  • #33988

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. Please try passing an additional accept attribute that cannot match any files. For example:

jsx
accept: `.${'n'.repeat(100)}`;
Upload by clicking

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Default Files

Use defaultFileList for uploaded files when page init.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Pictures with picture-circle type

Alternative display for picture-card.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
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.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Pictures Wall

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
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:

  1. limit the number of uploaded files.

  2. read from response and show file link.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Upload directory

You can select and upload a whole directory. Can still select files when uploading a folder in Safari?

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
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.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Customize preview file

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Transform file before request

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Custom action icon and extra info

Use showUploadList for custom action icons and extra information of files.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Crop image before uploading

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Upload manually

Upload files manually after beforeUpload returns false.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
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.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Max Count

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Aliyun OSS

Use Aliyun OSS upload example.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Drag sorting of uploadList

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Customize Progress Bar

Use progress for customize progress bar.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
xxx.png
yyy.png
zzz.png
image.pngimage.png
Uploading...
image.png
image.png

Click or drag file to this area to upload

Support for a single or bulk upload. Strictly prohibited from uploading company data or other banned files.

image.pngimage.png
image.pngimage.png
image.pngimage.png
image.pngimage.png
Uploading...
image.png
image.png
xxx.png
xxx.png(1.18MB)
yyy.png(1.18MB)
zzz.png(1.18MB)
image.pngimage.png
+ Upload
xxx.png
yyy.pngyyy.png
zzz.png
image1.png
image2.png
image3.png
image4.png
image.png