File Upload Component
The FileUpload component enables users to select and upload files to a server with features like drag-and-drop, validation, chunked uploads, retry logic, and progress tracking. It supports both single and multiple file uploads with sequential or parallel processing.
Usage
To import and use the File Upload component in your application, use the following code snippet:
Demos
Explore the demos of the React File Upload component. Refer to this page.
Props
The following table outlines the props for the File Upload component:
| Name | Type | Default | Description |
|---|---|---|---|
| accept | string | string[] | - | Specifies the accepted file types as MIME types or extensions (e.g., '.pdf', 'image/*', '.doc,.docx'). Can be a string or array of strings. |
| additionalData | Record<string, unknown> | - | Specifies additional form data to send with upload requests (e.g., |
| autoUpload | boolean | false | Specifies whether files should upload immediately after selection. When false, files are queued and must be uploaded manually. |
| children | node | - | Specifies compound children ( |
| chunkSize | number | - | Specifies the chunk size in bytes for chunked uploads of large files (e.g., 512 * 1024 for 512KB chunks). Chunked upload is enabled when this property is set. |
| defaultFiles | - | Specifies the initial list of FileItem objects with metadata and status. | |
| directory | boolean | false | Specifies whether directory selection is allowed instead of individual files. |
| dragDropEnabled | boolean | true | Specifies whether drag-and-drop file selection is enabled.
When set to |
| dropArea | RefObject<HTMLElement> | - | Specifies the drop target to handle the drag-and-drop upload.
Accepts a |
| files | - | Specifies the controlled file list. When provided, the parent fully owns
the list and must update it via | |
| headers | Record<string, string> | - | Specifies custom HTTP headers to include with upload requests. |
| maxFileSize | number | 30000000 | Specifies the maximum file size allowed in bytes (e.g., 5 * 1024 * 1024 for 5MB). |
| maxFiles | number | - | Specifies the maximum number of files allowed to be uploaded. |
| minFileSize | number | 0 | Specifies the minimum file size required in bytes. |
| multiple | boolean | true | Specifies whether multiple files can be selected at once. |
| removeUrl | string | - | Specifies the server endpoint URL for removing uploaded files. |
| retryCount | number | 0 | Specifies the maximum number of retry attempts for failed uploads. |
| retryDelay | number | 1000 | Specifies the delay in milliseconds between retry attempts. |
| saveUrl | string | - | Specifies the server endpoint URL for uploading files. |
| sequential | boolean | false | Specifies whether files should upload one at a time sequentially. When false, multiple uploads occur in parallel. |
| showCancel | boolean | true | Specifies whether to show the cancel button for in-progress uploads. |
| showProgressBar | boolean | true | Specifies whether to show the progress bar during file uploads. |
| showRemove | boolean | true | Specifies whether to show the remove button for files in the list. |
| showRetry | boolean | true | Specifies whether to show the retry button for failed uploads. |
| timeout | number | 30000 | Specifies the timeout duration in milliseconds for upload requests. |
| withCredentials | boolean | false | Specifies whether credentials (cookies, authorization headers) should be sent with upload requests. |
Events
The following table outlines the events for the File Upload component:
| Name | Type | Description |
|---|---|---|
| onCancel | (args: FileEvent) => void | Specifies the callback triggered when an in-progress file upload is canceled by the user. |
| onChange | (args: ChangeEvent) => void | Specifies the callback triggered when the file list changes (files added, removed, or status updated). |
| onComplete | (args: CompleteEvent) => void | Specifies the callback triggered when all files have completed uploading. |
| onError | (args: ErrorEvent) => void | Specifies the callback triggered when a file upload fails. |
| onPause | (args: FileEvent) => void | Specifies the callback triggered when an in-progress file upload is paused. |
| onProgress | (args: ProgressEventArgs) => void | Specifies the callback triggered during file upload to report progress. |
| onRemove | (args: FileEvent) => void | Specifies the callback triggered when a file is removed from the upload queue. |
| onResume | (args: FileEvent) => void | Specifies the callback triggered when a paused file upload is resumed. |
| onRetry | (args: FileEvent) => void | Specifies the callback triggered when a failed file upload is retried. |
| onSelect | (args: SelectEvent) => void | Specifies the callback triggered when files are selected from the file picker or dropped. |
| onStart | (args: FileEvent) => void | Specifies the callback triggered when a file upload starts. |
| onSuccess | (args: SuccessEvent) => void | Specifies the callback triggered when a file upload completes successfully. |
| onValidationError | (args: ValidationErrorEvent) => void | Specifies the callback triggered when a selected file fails validation. |