FileUpload
React file upload with drag and drop, accept and size validation, per-file status and progress, and a compact button variant. Fully controlled, RTL ready.
FileUpload is fully controlled: you own the files array, run the upload yourself, and report each file's status. Validation uses accept, maxSize, and maxFiles.
When to use
Use FileUpload for attachments such as ID scans, contracts, or supporting documents. Set accept, maxSize, and maxFiles to match the service rules, and report each file's status as your upload proceeds.
Use the button variant inside dense forms and the drop zone when files are the main task. Keep the rules visible in the helper text.
Examples
Props
Props declared by FileUpload. Native attributes of the underlying element pass through.
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "button" | "dropzone" | ||
filesrequired | UploadFile[] | Controlled list of files to render. The consumer is the source of truth. | |
onFilesAddedrequired | (accepted: File[]) => void | Called with the files that passed validation. The consumer wraps each in
an {@link UploadFile} (assigning an id) and starts the upload. | |
onFilesRejected | (rejections: FileRejection[]) => void | Called with files that failed validation. Never enter files. | |
onRemove | (id: string) => void | Per-row remove handler. Omit to hide the remove button. | |
accept | string | Native accept string (e.g. 'image/*,.pdf'). Also drives validation. | |
maxSize | number | Maximum size per file, in bytes. | |
maxFiles | number | Maximum total files (existing + incoming). When multiple is false this
is forced to 1. | |
multiple | boolean | Allow selecting/dropping more than one file. Defaults to true. | |
disabled | boolean | Disables the drop zone / button and the picker. | |
required | boolean | Marks the field required: renders the asterisk and sets the input's
required attribute. | |
label | react.ReactNode | Visible field label, auto-associated to the input. | |
title | react.ReactNode | ||
description | react.ReactNode | ||
buttonLabel | react.ReactNode | ||
errorMessage | react.ReactNode | Message shown below the field when error is true. | |
error | boolean | Marks the field invalid: sets aria-invalid and error styling. | |
removeLabel | string | Accessible label for the per-row remove button. Defaults to 'Remove'. | |
id | string | ||
className | string | ||
aria-label | string | Defines a string value that labels the current element. | |
aria-labelledby | string | Identifies the element (or elements) that labels the current element. |
Accessibility
The drop zone is also a button, so keyboard users can open the file picker with Enter or Space. Rejections are announced through a role="alert" list with the reason for each file.
Each file row exposes its status and a labelled remove button. The field label, helper text, and error are wired like TextInput.