Upload

Upload file by selecting or dragging.

Install

npm install @arco-design/web-react@2.66.18

Import @arco-design/web-react/dist/css/arco.css at the entry and set the locale with ConfigProvider. React 19 projects must also import @arco-design/web-react/es/_util/react-19-adapter first, or imperative APIs such as Message and Modal cannot render.

Examples

• Basic: The Basic usage.
• Avatar: Click to upload user's avatar, and validate size and format of picture with beforeUpload.
• upload list: Default upload list.
• pictures wall: onPreview will be executed when user click preview icon. The built-in image preview can be enabled via the imagePreview property. (The imagePreview property is supported in 2.41.0)
• drag and drop: Drag files to a specific area, to upload.
• pictures with list: Pictures with list style.
• upload manually: If autoUpload equals false, files will not be uploaded automatically after being selected. You can submit them by uploadRef.submit method.submit will only upload files that are in fileList.
• beforeUpload: The function will be executed before each file upload. Uploading will be aborted when the return value is false or a Promise which resolve(false) or reject.
• beforeUpload: The function will be executed before each file upload. Uploading will be aborted when the return value is false or a Promise which resolve(false) or reject.
• onRemove: The function will be executed when user click remove icon. Remove actions will be aborted when the return value is false or a Promise which resolve(false) or reject
• Limit: Limit the maximum number of uploaded files.
• Customize children: Customize the node that triggers the upload operation.
• custom icon: showUploadList can be an object to customize previewIcon, removeIcon, fileIcon, reuploadIcon, cancelIcon, startIcon, errorIcon and fileName.
• Customize upload list: Customize the display of uploaded files
• Custom request: Override for the default xhr behavior allowing for additional customization and ability to implement your own XMLHttpRequest
• customize progress bar: Use progressProps for customize progress bar.
• Upload directory: Upload directory.

Examples come from the official Arco Design repository (MIT) at the commit published as npm 2.66.18. Some use online images or upload endpoints; network requests are disabled in previews.

API

Upload

UploadListProps

File upload list display

UploadItem

RequestOptions

export type RequestOptions = Pick<
  UploadProps,
  "headers" | "name" | "data" | "withCredentials" | "action" | "method"
> & {
  /** 更新当前文件的上传进度 。percent: 当前上传进度百分比 */
  onProgress: (percent: number, event?: ProgressEvent) => void;
  /** 上传成功后，调用onSuccess方法，传入的response参数将会附加到当前上传文件的reponse字段上 */
  onSuccess: (response?: object) => void;
  /** 上传失败后，调用onError方法，传入的 response 参数将会附加到当前上传文件的response字段 */
  onError: (response?: object) => void;
  /** 当前上传文件 */
  file: File;
};

UploadRequestReturn

export interface UploadRequestReturn {
  abort?: () => void;
  [key: string]: any;
}

CustomIconType

export type CustomIconType = {
  previewIcon?: ReactNode;
  removeIcon?: ReactNode;
  fileIcon?: ReactNode;
  reuploadIcon?: ReactNode;
  cancelIcon?: ReactNode;
  startIcon?: ReactNode;
  errorIcon?: ReactNode;
  successIcon?: ReactNode;
  fileName?: (file: UploadItem) => ReactNode;
  // 2.34.0
  progressRender?: (
    file: UploadItem,
    originDom: ReactNode
  ) => React.ReactElement;
  // 2.34.0
  imageRender?: (file: UploadItem) => React.ReactNode;
};

UploadStatus

export type UploadStatus = "init" | "uploading" | "done" | "error";

Methods

// Custom icons
type CustomIconType = {
  previewIcon?: ReactNode;
  removeIcon?: ReactNode;
  fileIcon?: ReactNode;
  reuploadIcon?: ReactNode;
  cancelIcon?: ReactNode;
  startIcon?: ReactNode;
  errorIcon?: ReactNode;
  fileName?: (file: UploadItem) => ReactNode;
  progressRender?: (file: UploadItem, originDom: ReactNode) => ReactElement; // 2.34.0
  imageRender?: (file: UploadItem) => ReactNode; // 2.34.0
}

Q&A

How to control the status and progress of uploaded files?

See example, You can directly set the status, percent and other fields for each element in the fileList.