# Upload

- Page: https://jiguang132.com/resources/ant-design/docs/upload
- Resource: Ant Design (https://jiguang132.com/resources/ant-design.md)
- All guides: https://jiguang132.com/resources/ant-design/docs.md

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](#jguang-common-props)

| Property | Description | Type | Default | Version | [Global Config](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| 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 \| [AcceptObject](#acceptobject) | - |  | 6.4.0 |
| action | Uploading URL | string \| (file) => Promise<string> | - |  | × |
| 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：this function is not supported in IE9** | (file: [RcFile](#rcfile), fileList: [RcFile[]](#rcfile)) => boolean \| Promise<File> \| `Upload.LIST_IGNORE` | - |  | × |
| customRequest | Override for the default xhr behavior allowing for additional customization and the ability to implement your own XMLHttpRequest | ( options: [RequestOptions](#request-options), info: { defaultRequest: (option: [RequestOptions](#request-options)) => void; } ) => void | - | defaultRequest: 5.28.0 | 5.27.0 |
| classNames | Customize class for each semantic structure inside the component. Supports object or function. | Record<[SemanticDOM](#semantic-dom), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), string> | - |  | 6.0.0 |
| data | Uploading extra params or function which can return uploading extra params | object \| (file) => object \| Promise&lt;object> | - |  | × |
| defaultFileList | Default list of files that have been uploaded | object\[] | - |  | × |
| directory | Support upload whole directory ([caniuse](https://caniuse.com/#feat=input-file-directory)) | boolean | false |  | × |
| disabled | Disable upload button. 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. | boolean | false |  | × |
| 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)\[] | - |  | × |
| headers | Set request headers, valid above IE10 | object | - |  | × |
| iconRender | Custom show icon | (file: UploadFile, listType?: UploadListType) => ReactNode | - |  | × |
| isImageUrl | Customize if render &lt;img /> in thumbnail | (file: UploadFile) => boolean | [(inside implementation)](https://github.com/ant-design/ant-design/blob/4ad5830eecfb87471cd8ac588c5d992862b70770/components/upload/utils.tsx#L47-L68) |  | × |
| itemRender | Custom item of uploadList | (originNode: ReactElement, file: UploadFile, fileList: object\[], actions: { download: function, preview: function, remove: function }) => React.ReactNode | - | 4.16.0 | × |
| listType | Built-in stylesheets, support for four types: `text`, `picture`, `picture-card` or `picture-circle` | string | `text` | `picture-circle`(5.2.0+) | × |
| maxCount | Limit the number of uploaded files. Will replace current one when `maxCount` is `1` | number | - | 4.10.0 | × |
| method | The http method of upload request | string | `post` |  | × |
| 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 |  | × |
| name | The name of uploading file | string | `file` |  | × |
| openFileDialogOnClick | Click open file dialog | boolean | true |  | × |
| pastable | Support paste file | boolean | false | 5.25.0 | × |
| previewFile | Customize preview file logic | (file: File \| Blob) => Promise&lt;dataURL: string> | - |  | × |
| progress | Custom progress bar | [ProgressProps](/components/progress/#api) (support `type="line"` only) | { strokeWidth: 2, showInfo: false } | 4.3.0 | 6.4.0 |
| 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 | × |
| styles | Customize inline style for each semantic structure inside the component. Supports object or function. | Record<[SemanticDOM](#semantic-dom), CSSProperties> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), CSSProperties> | - |  | 6.0.0 |
| withCredentials | The ajax upload with cookie sent | boolean | false |  | × |
| onChange | A callback function, can be executed when uploading state is changing. It will trigger by every uploading phase. see [onChange](#onchange) | function | - |  | × |
| 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 | - |  | × |

## Interface

### RcFile

Extends [File](https://developer.mozilla.org/en-US/docs/Web/API/File).

| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| uid | unique id. Will auto-generate when not provided | string | - | - |
| lastModifiedDate | A Date object indicating the date and time at which the file was last modified | date | - | - |

### UploadFile

Extends [File](https://developer.mozilla.org/en-US/docs/Web/API/File) with additional props.

| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| crossOrigin | CORS settings attributes | `'anonymous'` \| `'use-credentials'` \| `''` | - | 4.20.0 |
| name | File name | string | - | - |
| percent | Upload progress percent | number | - | - |
| status | Upload status. Show different style when configured | `error` \| `done` \| `uploading` \| `removed` | - | - |
| thumbUrl | Thumb image url | string | - | - |
| uid | unique id. Will auto-generate when not provided | string | - | - |
| url | Download url | string | - | - |

### RequestOptions {#request-options}

| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| action | Uploading URL | string | - | - |
| data | Uploading extra params or function which can return uploading extra params | Record<string, unknown> | - | - |
| filename | file name | string | - | - |
| file | File object containing upload information | [UploadFile](#uploadfile) | - | - |
| withCredentials | The ajax upload with cookie sent | boolean | - | - |
| headers | Set request headers, valid above IE10 | Record<string, string> | - | - |
| method | The http method of upload request | string | - | - |
| onProgress | Progress event callback | (event: object, file: UploadFile) => void | - | - |
| onError | Error callback when upload fails | (event: object, body?: object) => void | - | - |
| onSuccess | Success callback when upload completes | (body: object, fileOrXhr?: UploadFile \| XMLHttpRequest) => void | - | - |

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

### AcceptObject

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

Configuration object for file type acceptance rules.

| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| format | Accepted file types, same as native input accept attribute. Supports MIME types, file extensions, etc. See [input accept Attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept) | string | - |  |
| filter | File filtering rule. When set to `'native'`, uses browser native filtering behavior; when set to a function, allows custom filtering logic. Function returns `true` to accept the file, `false` to reject | `'native'` \| `(file: RcFile) => boolean` | - |  |

## Semantic DOM

| Semantic node | Native description | Version |
| --- | --- | --- |
| `root` | Root container element with layout styles, disabled text color, user-select control, cursor styles and other basic styles | 6.0.0 |
| `list` | File list container with layout arrangement, transition animations, spacing control and other styles | 6.0.0 |
| `item` | File item element with padding, background color, border styles, hover effects, status colors, transition animations and other styles | 6.0.0 |
| `trigger` | Upload button container with button styles, disabled state, visibility control and other styles | 6.3.0 |

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.

| Token | Type | Native description |
| --- | --- | --- |
| `actionsColor` | `string` | Action button color |
| `pictureCardSize` | `number` | Size of list items in card type (affects both picture-card and picture-circle) |

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

```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? {#faq-server-implement}

- You can consult [jQuery-File-Upload](https://github.com/blueimp/jQuery-File-Upload/wiki#server-side) about how to implement server side upload interface.
- There is a mock example of [express](https://github.com/react-component/upload/blob/211979fdaa2c7896b6496df7061a0cfc0fc5434e/server.js) 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.

<img alt="click restart button on Chrome" src="https://github.com/ant-design/ant-design/assets/507615/1509b25f-4cd3-41b2-9415-90394ad08273" width="800" />

Ref:

- [#48007](https://github.com/ant-design/ant-design/issues/48007)
- [#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)

### 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](https://stackoverflow.com/q/55649945/3040605). You can solve this issue through `accept` configuration, for example:

```tsx
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 {#jguang-common-props}


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

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| style | The additional style | CSSProperties | - |
| className | The additional css class | string | - |
| rootClassName | ClassName on the root element | string | - |
| autoFocus | Auto focus when component mounted, only effective for focusable elements like forms, links, etc. | boolean | false |


## Install and reproduce an example

```bash
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.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt