Upload

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/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> <code src="./demo/picture-circle.tsx">Pictures with picture-circle type</code> <code src="./demo/fileList.tsx">Complete control over file list</code> <code src="./demo/drag.tsx">Drag and Drop</code> <code src="./demo/paste.tsx" version="5.25.0">Paste</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> <code src="./demo/upload-custom-action-icon.tsx">Custom action icon and extra info</code> <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> <code src="./demo/style-class.tsx" version="6.0.0">Custom semantic dom styling</code> <code src="./demo/component-token.tsx" debug>Component Token</code> <code src="./demo/debug-disabled.tsx" debug>Debug Disabled Styles</code>

API

Common props ref：Common props

Interface

RcFile

Extends File.

UploadFile

Extends File with additional props.

RequestOptions {#request-options}

onChange

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

When uploading state change, it returns:

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

1. file File object for the current operation.

   jsxCopy

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

AcceptObject

{
  format: string;
  filter?: 'native' | ((file: RcFile) => boolean);
}

Configuration object for file type acceptance rules.

Semantic DOM

<code src="./demo/_semantic.tsx" simplify="true"></code>

Design Token

<ComponentTokenTable component="Upload"></ComponentTokenTable>

FAQ

How do I implement upload server side? {#faq-server-implement}

• 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. {#faq-show-download-link}

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

How to use customRequest? {#faq-custom-request}

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? {#faq-filelist-controlled-status}

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 }? {#faq-on-change-return-type}

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? {#faq-chrome-file-picker}

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

Ref:

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

Can still select files when uploading a folder in Safari? {#faq-safari-folder-upload}

Inside the upload component, we use the directory and webkitdirectory properties to control the input to implement folder selection, but it seems that in Safari's implementation, it doesn't prevent users from selecting files. You can solve this issue through accept configuration, for example:

accept = {
  // Do not allow selecting any files
  format: `.${'n'.repeat(100)}`,
  // Accept all files within the folder after folder selection
  filter: () => true,
};