Upload

Used to select and upload files or drag and drop files.

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 · basic

• Avatar · avatar

• Default Files · defaultFileList

• Pictures Wall · picture-card

• Pictures with picture-circle type · picture-circle

• Complete control over file list · fileList

• Drag and Drop · drag

• Paste · paste

• Upload directory · directory

• Upload manually · upload-manually

• Upload png file only · upload-png-only

• Pictures with list style · picture-style

• Customize preview file · preview-file

• Max Count · max-count

• Transform file before request · transform-file

• Aliyun OSS · upload-with-aliyun-oss

• Custom action icon and extra info · upload-custom-action-icon

• Drag sorting of uploadList · drag-sorting

• Crop image before uploading · crop-image

• Customize Progress Bar · customize-progress-bar

• Custom semantic dom styling · style-class

API

Common props ref：Common props

Interface

RcFile

Extends File.

UploadFile

Extends File with additional props.

RequestOptions

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.

   {
      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

Semantic description source: vendor/components/upload/demo/_semantic.tsx

Design Token

Types, inheritance and declarations retain the pinned native source. Defaults are computed by the native theme and may be overridden by ConfigProvider; this table does not invent static defaults.

Declaration source: vendor/components/upload/style/index.ts

import type { CSSObject } from '@ant-design/cssinjs';

import { resetComponent } from '../../style';

import { genCollapseMotion } from '../../style/motion';

import type { FullToken, GenerateStyle, GetDefaultToken } from '../../theme/internal';

import { genStyleHooks, mergeToken } from '../../theme/internal';

import genDraggerStyle from './dragger';

import genListStyle from './list';

import genMotionStyle from './motion';

import { genPictureCardStyle, genPictureStyle } from './picture';

import genRtlStyle from './rtl';

export interface ComponentToken {
  /**
   * @desc 操作按扭颜色
   * @descEN Action button color
   */
  actionsColor: string;
  /**
   * @desc 卡片类型文件列表项的尺寸（对 picture-card 和 picture-circle 生效）
   * @descEN Size of list items in card type (affects both picture-card and picture-circle)
   */
  pictureCardSize: number;
}

export interface UploadToken extends FullToken<'Upload'> {
  uploadThumbnailSize: number | string;
  uploadProgressOffset: number | string;
  uploadPicCardSize: number | string;
}

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.

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 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,
};

Shared native props

Tips: The following generic properties apply to most antd components; those not supported are described separately.

Install and reproduce an example

npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23

Use ConfigProvider and native App; configure dayjs locale separately. Each example lists its complete source files and additional pinned dependencies in View code. Example names select demos, not universal component props. See the resource setup guide for theme, locale and SSR.

Native type references

The source viewer includes unchanged native implementations and the following source declarations. Inherited types remain in their native packages. English source comments are preserved as code reference.

• vendor/components/upload/Dragger.tsx
• vendor/components/upload/Upload.tsx
• vendor/components/upload/UploadList/ListItem.tsx
• vendor/components/upload/UploadList/index.tsx
• vendor/components/upload/index.tsx
• vendor/components/upload/interface.ts
• vendor/components/upload/style/index.ts

Source and license

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

Original bilingual prose and executable examples are retained. Website-only embeds and token tables are expanded locally. Ant Design is MIT; separately listed dependency notices also apply. Upload previews block outbound requests and do not provide a backend.

Local example adaptations

• authored/demos/upload/crop-image.tsx: Set native cropper title, reset and action labels from ConfigProvider locale instead of browser language. Original reference: vendor/components/upload/demo/crop-image.tsx.
• authored/demos/upload/preview-file.tsx: Handle unavailable or invalid thumbnail-service responses with a native warning and an empty-thumbnail fallback, without reporting upload success. Original reference: vendor/components/upload/demo/preview-file.tsx.
• authored/demos/upload/drag-sorting.tsx: Ignore drops outside the upload list and missing item identities instead of passing an invalid negative index to arrayMove. Original reference: vendor/components/upload/demo/drag-sorting.tsx.

Copy the adapted sourceFiles listed by the example; upstream reference source remains unchanged. See LOCAL_CHANGES.md.