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:

NameTypeDefaultDescription
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., { userId: '123' }).

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 (<BrowseButton>, <DragHint>, <FileList>, <Actions>) for the composition API.

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 false, users can only select files through the browse button.

dropArea
RefObject<HTMLElement>
-

Specifies the drop target to handle the drag-and-drop upload. Accepts a RefObject<HTMLElement> pointing to the target element. By default, the component creates a wrapper around the file input that acts as the drop target.

files
-

Specifies the controlled file list. When provided, the parent fully owns the list and must update it via onChange. The component will not modify its own state — every change fires onChange and waits for the new value to flow back through this prop.

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:

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