On this page
FileUpload
Headless, unstyled file picker and drop zone. Owns a hidden <input type="file">, checks each file against accept and maxSize for the picker and for drops, and reports the rest through onReject. FileUpload.useFileUpload() reads the files and actions inside the root; FileUpload.useObjectUrl(file) gives a preview URL that is revoked when the file changes or the caller unmounts.
Use for
- a file picker behind your own button
- a drag and drop zone for files
- a metadata or key file upload
- a list of picked files with image thumbnails and remove buttons
Practices
| Guidance | Practice |
|---|---|
| Don’t | Use it for an avatar or logo row. Use AvatarUpload instead. |
| Don’t | Render your own <input type="file">. The root owns one. |
| Do | Show feedback from onReject. A rejected file is never added, while the accepted files in the same batch are. |
| Do | Treat data-drag-rejected as a hint. During a drag the browser hides file names, so extension-only accept entries and blank types are not flagged. |
| Do | Use FileUpload.useObjectUrl to show a picked image in your own element, instead of URL.createObjectURL by hand. |
API reference
FileUpload.Root
Holds the selected files and the hidden input. Renders a div, or the render element, with data-empty and data-disabled. In single mode a new pick replaces the file; in multiple mode picks append.
| Prop | Type | Description |
|---|---|---|
value | File[] | The selected files, when controlled. |
defaultValue | File[] | The selected files on mount, when uncontrolled.Default: [] |
onValueChange | (files: File[]) => void | Called with the full file list whenever it changes. |
multiple | boolean | Allows more than one file.Default: false |
accept | string | Native accept string, such as image/*,.pdf. Also applied to drops. |
maxSize | number | Largest size in bytes for one file. |
onReject | (rejections: FileRejection[]) => void | Called with each rejected file and its reason: accept, size, or overflow for extra files in single mode. |
disabled | boolean | Disables the trigger, the drop zone and the picker.Default: false |
inputId | string | The hidden input id, so a <label htmlFor> opens the picker.Default: a generated id |
FileUpload.Trigger
A button that opens the native picker. Carries data-disabled.
FileUpload.Dropzone
A div that takes dropped files and ignores drags that carry none. Carries data-dragging, data-drag-rejected and data-disabled.
FileUpload.Item
Wraps one picked file for ItemPreview and ItemDelete. Carries data-image for an image file.
| Prop | Type | Description |
|---|---|---|
file | File | The file it represents, usually from useFileUpload().files. |
FileUpload.ItemPreview
An img of the item's file, with the file name as alt. Renders nothing for a file that is not an image.
FileUpload.ItemDelete
A button that removes the item's file. Carries data-disabled.
Examples
A drop zone with a file list
<FileUpload.Root accept='image/*' multiple onReject={showRejections}>
<FileUpload.Dropzone>
<FileUpload.Trigger>Choose files</FileUpload.Trigger>
</FileUpload.Dropzone>
<FileList />
</FileUpload.Root>
function FileList() {
const { files } = FileUpload.useFileUpload();
return files.map(file => (
<FileUpload.Item key={file.name} file={file}>
<FileUpload.ItemPreview />
<FileUpload.ItemDelete>Remove</FileUpload.ItemDelete>
</FileUpload.Item>
));
}Related
AvatarUpload- ImageCropper