{"id":11641,"library":"rc-upload","title":"React Upload Component","description":"rc-upload is a lightweight, unstyled React UI component for handling file uploads. It provides foundational upload capabilities such as drag-and-drop, folder uploads, and paste-from-clipboard functionality without imposing any specific visual design, allowing developers full control over the user interface. The current stable version is 4.11.0. The project maintains an active release cadence, with minor versions released periodically to introduce new features, address bugs, and update dependencies. Its key differentiators include its headless architecture, extensive customization options via props like `customRequest` and `beforeUpload`, and support for modern browser-based upload features. It is a core utility often used as a building block for more complex upload components.","status":"active","version":"4.11.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/react-component/upload","tags":["javascript","react","react-component","react-upload","upload","typescript"],"install":[{"cmd":"npm install rc-upload","lang":"bash","label":"npm"},{"cmd":"yarn add rc-upload","lang":"bash","label":"yarn"},{"cmd":"pnpm add rc-upload","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React component rendering.","package":"react","optional":false},{"reason":"Peer dependency for React component rendering.","package":"react-dom","optional":false}],"imports":[{"note":"The primary `Upload` component is exported as a default. Attempting to import it as a named export will fail.","wrong":"import { Upload } from 'rc-upload';","symbol":"Upload","correct":"import Upload from 'rc-upload';"},{"note":"Importing types directly as values might lead to bundling issues or unnecessary code. Use `import type` for explicit type imports.","wrong":"import { UploadProps } from 'rc-upload';","symbol":"UploadProps","correct":"import type { UploadProps } from 'rc-upload';"},{"note":"This type extends the standard `File` interface and is used internally and in callback functions like `beforeUpload` or `onStart`.","symbol":"RcFile","correct":"import type { RcFile } from 'rc-upload';"}],"quickstart":{"code":"import React, { useState } from 'react';\nimport Upload from 'rc-upload';\nimport type { UploadProps, RcFile } from 'rc-upload';\n\nconst App: React.FC = () => {\n const [fileList, setFileList] = useState([]);\n\n const handleStart: UploadProps['onStart'] = (file) => {\n console.log('onStart', file.name);\n setFileList((prev) => [...prev, { ...file, status: 'uploading' }]);\n };\n\n const handleSuccess: UploadProps['onSuccess'] = (response, file) => {\n console.log('onSuccess', response, file.name);\n setFileList((prev) => prev.map(f => f.uid === file.uid ? { ...f, status: 'done' } : f));\n };\n\n const handleError: UploadProps['onError'] = (err, response, file) => {\n console.error('onError', err, response, file.name);\n setFileList((prev) => prev.map(f => f.uid === file.uid ? { ...f, status: 'error' } : f));\n };\n\n const handleProgress: UploadProps['onProgress'] = (event, file) => {\n console.log('onProgress', Math.round(event.percent || 0) + '%', file.name);\n };\n\n const beforeUpload: UploadProps['beforeUpload'] = (file, currentFileList) => {\n const isLt2M = file.size / 1024 / 1024 < 2;\n if (!isLt2M) {\n alert('File must be smaller than 2MB!');\n return false; // Stop upload\n }\n console.log('beforeUpload', file.name, currentFileList.length);\n return true; // Proceed with upload\n };\n\n return (\n
\n

File Upload Demo

\n \n \n \n {fileList.length > 0 && (\n
\n

Upload Status:

\n
    \n {fileList.map((file) => (\n
  • \n {file.name} - {file.status} {file.status === 'uploading' && '(in progress)'}\n
    • \n ))}\n
\n
\n )}\n
\n );\n};\n\nexport default App;","lang":"typescript","description":"Demonstrates a basic file upload component with a mock server action and callback handlers for `onStart`, `onSuccess`, `onError`, `onProgress`, and `beforeUpload` to manage file state and validation."},"warnings":[{"fix":"Replace `directory={true}` with `folder={true}` when enabling directory uploads.","message":"The `directory` prop was deprecated in `v4.10.0` in favor of the `folder` prop for uploading entire directories. While `directory` might still function, it is not recommended and could be removed in future major versions.","severity":"breaking","affected_versions":">=4.10.0"},{"fix":"Wrap the `Upload` component with custom UI elements (e.g., a button, a drag-and-drop area) and apply your own CSS for styling.","message":"`rc-upload` is a headless component and does not provide any default UI or styling. Developers must implement their own visual presentation and interaction around the `Upload` component.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"In modern projects, always use `import Upload from 'rc-upload';`.","message":"While the README historically showed CommonJS `require('rc-upload')` for usage, modern React applications primarily use ES module `import` syntax. Using `require` in an ESM-only environment or attempting named imports when only a default export exists will lead to errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review and adjust the type signatures of custom `beforeUpload` functions to align with the updated typings, ensuring correct handling of the `file` and `fileList` arguments.","message":"The type annotations for the `beforeUpload` function were updated in `v4.11.0`. While this is primarily a TypeScript-related change and not a functional one, projects with strict TypeScript configurations or custom `beforeUpload` implementations might encounter type errors after upgrading.","severity":"breaking","affected_versions":">=4.11.0"},{"fix":"Verify the package name in your `package.json` and `import` statements. If you intend to use `rc-upload`, ensure your dependencies list `rc-upload` and your imports are `from 'rc-upload'`.","message":"`rc-upload` is distinct from `@rc-component/upload`. Although the GitHub repository `react-component/upload` shows commits related to both, `@rc-component/upload` is a separate package (currently at v1.x) and not a direct replacement or rename of `rc-upload` (v4.x). Ensure you are installing and importing from the correct package, `rc-upload`.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change the import statement to `import Upload from 'rc-upload';`","cause":"Attempting to import `Upload` as a named export when it is exported as a default export.","error":"Error: 'Upload' is not exported from 'rc-upload'"},{"fix":"Ensure the `action` prop is either a `string` (e.g., `action=\"/upload-target\"`) or a function returning a `string` or `Promise` (e.g., `action={(file) => `/api/upload/${file.name}`}`).","cause":"Providing an incorrect type for the `action` prop, which expects a URL string or a function that returns a URL.","error":"Type 'boolean' is not assignable to type 'string | ((file: File) => string | Promise)'"},{"fix":"Replace `directory={true}` with `folder={true}` to enable folder uploads.","cause":"Using the deprecated `directory` prop (removed since v4.10.0) instead of the `folder` prop.","error":"Property 'directory' does not exist on type 'UploadProps'. Did you mean 'folder'?"}],"ecosystem":"npm"}