File Upload
The uploading experience: a dropzone that reads the drag before the drop, then an upload queue with progress, time left, retry and a summary. Built on File Card rows.
Try it yourself. This one is live, and its code is right below.
Installation#
Usage#
Give File Upload an onUpload and it runs the whole thing: validation, the queue, progress, time left, retry, cancel and an announced outcome.
The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.
Have a license? Unlock it here
Leave it out and File Upload owns only selection: it emits accepted files through onFiles and rejections through onReject, and you own the list. Render the resulting rows with File Card inside a FileUploadList - the two compose into the full experience.
The preview is yours to explore. Its code comes with a Pro license, paid once and used in every project.
Have a license? Unlock it here
Anatomy#
import {
FileUpload,
FileUploadDropzone,
FileUploadIcon,
FileUploadTitle,
FileUploadLink,
FileUploadDescription,
FileUploadTrigger,
FileUploadSources,
FileUploadSource,
FileUploadQueue,
FileUploadSummary,
FileUploadList,
FileUploadGrid,
} from "@/components/ui/file-upload"
<FileUpload>
<FileUploadDropzone>
<FileUploadIcon />
<FileUploadTitle>
<FileUploadLink />
</FileUploadTitle>
<FileUploadDescription />
<FileUploadTrigger />
<FileUploadSources>
<FileUploadSource />
</FileUploadSources>
</FileUploadDropzone>
<FileUploadQueue />
<FileUploadSummary />
<FileUploadList />
<FileUploadGrid />
</FileUpload>The FileUpload root holds a hidden file input and the shared state; the FileUploadDropzone is the dashed drop surface, filled with a FileUploadIcon, a FileUploadTitle with the FileUploadLink sitting inline in the sentence, and a FileUploadTrigger (or a FileUploadSources row).
The panel decides what it is from what you put in it. With only a sentence inside, it is the button: one tab stop, named by the title and described by the description, and the FileUploadLink becomes styled text. Add a FileUploadTrigger or source tiles and it steps back to a plain drop target, so those controls keep their own Enter and Space and a button never sits inside a button.
Upload queue#
Pass onUpload and put FileUploadQueue and FileUploadSummary under the dropzone. Every dropped file gets a row, including the ones that fail validation: a file that is too big or the wrong type stays in the list with its reason instead of vanishing. A failed upload keeps its bar where it stopped, in red, with Retry beside it; a removed or cancelled row aborts its request through signal.
Bytes are written in the total’s unit (“0.6 of 1.6 MB”) and time left is estimated from the pace so far, falling back to “almost done” for the last few seconds. Settled, failed and rejected files are announced in a polite live region.
Drag feedback#
The dropzone reads the drag before the drop. The browser shares how many files are coming and their types, so the title hands over to a count (“Drop 3 files”), says how many will make it (“Drop to add 2 of 3 files”), or warns while there is still time to let go elsewhere (“This file type isn’t accepted”). An accepted drag lifts the glyph, the way a picked-up object rises, and edges the panel in brand; a rejected one turns it destructive. A drop where nothing passes plays the same shake as every other rejection in Koala. Sizes are only known after the drop, so a file that is too big is caught there.
Override the line with dragLabel on FileUploadTitle, or pass null to keep the sentence. Drag a few files over the demo above to try it.
Custom rows#
The queue keeps the motion and the bookkeeping; the row is yours. Pass a render function to FileUploadQueue and compose any File Card anatomy from the item.
Import shortcuts#
The local disk isn’t the only place a file lives. Introduce a FileUploadSources row with a labelled Divider and give each provider a FileUploadSource tile. A source owns its own picker - an OAuth flow, a provider SDK, your own modal - so it takes a onClick and deliberately does not route back into the native file dialog.
The mark is children, not a brand prop: pass whatever you own - a real logo, an img, or a Koala glyph.
Thumbnail layout#
When the upload is the picture, a filename row gets in the way. Swap FileUploadList for FileUploadGrid and give each File Card layout="tile": the thumbnail fills the square and FileCardActions become a scrim that fades in on hover or keyboard focus. The tile never moves - the photo and the scrim carry the whole interaction.
Row states#
A row in flight reads either way. Put the bar under the name with <FileCardProgress hideValue /> and move the percentage out to a FileCardValue on the right edge; or drop the bar for a plain FileCardMeta line when the pause and cancel controls matter more than the number. Once it lands, FileCardStatus reads the card’s state and lights the check on its own.
Browse button#
No room for a dropzone? Drop a FileUploadTrigger on its own - it opens the same picker, so an attach action is a single button. The trigger reuses the DS Button, so it inherits every variant and size.
Avatar picker#
Compose the trigger with an Avatar for a profile-photo picker: a single-file image/* upload that swaps the avatar in place, with a “Change photo” / “Remove” pair.
JPG, GIF or PNG. 2 MB max.
Validation#
Pass accept, maxSize (bytes), and multiple, and dropped or picked files are split for you: onFiles gets the keepers, onReject gets the rest with a reason (type, size, or count) so you can surface a precise message.
Density#
Density is Koala’s cross-cutting spacing axis (see Density). For File Upload it tunes the dropzone padding, the rhythm between its blocks, and the glyph. Density resolves prop → nearest DensityProvider → compact, so an unset dropzone renders compact; ask for comfortable to get the roomy panel.
Disabled#
Pass disabled to the root and the whole control goes inert - the dropzone stops accepting drops and clicks, the link, trigger and sources disable, and the surface dims.
Keyboard#
Tab reaches the dropzone (or its trigger and source tiles), then Retry and Cancel or Remove in every row, then the summary’s actions. Enter or Space on the dropzone opens the file picker. Every row’s bar is a progressbar named after its file.
Motion#
Rows grow open one after another for each drop and fold shut when removed, so the list never jumps. The check settles in on the spring curve when a file lands. A failed upload and a rejected drop share Koala’s three-swing shake. The title’s hand-over is a relay: the sentence leaves on the fast beat and the drag line arrives after it. With reduced motion everything switches at once.
API reference#
FileUpload
The root: holds the hidden file input, validates every drop or pick, and shares the picker with its parts. It owns selection only; you keep the file list. Forwards native <div> props except onError; every part accepts className, merged last.
| Prop | Type | Default | Description |
|---|---|---|---|
| onFiles | (files: File[]) => void | - | Accepted files from a drop or browse. Fires only when at least one file passes. |
| onReject | (rejections: FileRejection[]) => void | - | Rejected files, each { file, reason } with reason "type", "size" or "count". |
| onUpload | (file: File, { onProgress, signal }) => Promise<unknown> | - | Uploads one file. Report progress from 0 to 1 with onProgress; reject to fail the row (the error's message is shown and Retry calls it again). signal aborts when the row is cancelled or removed. Passing it turns the queue on: FileUploadQueue, FileUploadSummary and useFileUpload read from it. |
| onQueueChange | (items: FileUploadItem[]) => void | - | Every change of the queue. Each item is { id, file, name, size, status, progress, eta?, error?, rejection?, failures }. |
| accept | string | - | Native input accept, e.g. "image/*,.pdf"; checked against picked and dropped files, and against dragged ones before the drop. |
| multiple | boolean | false | Allow more than one file per selection; without it, extra files are rejected with "count". |
| maxSize | number | - | Max size per file, in bytes. Larger files are rejected with "size". |
| disabled | boolean | false | Make the whole control inert: the dropzone stops taking drops and clicks, and the link, trigger and sources disable. |
| density | "comfortable" | "compact" | "compact" | Dropzone padding, block rhythm and glyph size. Falls back to the nearest DensityProvider. |
| Data attribute | Description |
|---|---|
| data-disabled | Present while disabled. |
FileUploadDropzone
The dashed drop surface; a click anywhere opens the picker. With no FileUploadTrigger or FileUploadSource inside, it is the button itself: one tab stop, named by the title, described by the description, opened with Enter or Space. With them, it stays a drop target and they are the keyboard path. A drop or pick where nothing passes plays the shared shake. Forwards all native <div> props.
| Data attribute | Description |
|---|---|
| data-dragging | Present while files are dragged over the panel. |
| data-drag | "accept" or "reject" while dragging: reject when every dragged file has the wrong type, or several files reach a single-file upload. |
| data-disabled | Present while the root is disabled. |
FileUploadIcon
The glyph crowning the dropzone, decorative. It lifts and turns full ink while an accepted drag hovers, and turns destructive on a rejected one. Defaults to an image placeholder; pass your own icon as children. Forwards all native <div> props.
FileUploadTitle
The dropzone's one balanced sentence, with a FileUploadLink inline. While files hover, the sentence hands over to a drag line ("Drop 3 files", "Drop to add 2 of 3 files", "This file type isn't accepted"). Forwards all native <div> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| dragLabel | ReactNode | ((drag: FileUploadDrag) => ReactNode) | - | Replaces the drag line. drag is { count, accepted, reason } with reason "type", "count" or null. Pass null to keep the sentence while dragging. |
FileUploadDescription
Muted supporting copy. Without children it writes itself from accept and maxSize ("Images, PDF or XLSX, up to 25 MB"). Forwards all native <div> props.
FileUploadLink
The inline picker word inside the sentence, in full ink; renders "click here" when it has no children. A button of its own when the dropzone holds a trigger or sources; plain styled text when the dropzone is the button, so a button never sits inside a button.
FileUploadTrigger
A Button that opens the picker, inside the dropzone or on its own; renders "Browse files" when it has no children. Takes every Button prop.
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | ButtonProps["variant"] | "outline" | Any Button variant. |
FileUploadSources
The layout-only "or import from" row of FileUploadSource tiles. Forwards all native <div> props.
FileUploadSource
One import shortcut: the provider's mark as children in a bordered tile, its name beneath. Wire onClick to that provider's picker; it never opens the local file dialog. Forwards all native <button> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| label* | React.ReactNode | - | The name under the mark, e.g. "Google Drive"; also the button's accessible name. |
FileUploadList
A layout-only column for the resulting FileCard rows; the exported formatBytes(bytes) turns file.size into a meta line ("1.8 MB"). Forwards all native <div> props.
FileUploadQueue
The upload rows, once onUpload is set. Each row grows in, one after another per drop, and folds away when removed. Renders a FileUploadQueueItem per file, or pass a render function as children for your own row. Forwards all native <div> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| children | (item: FileUploadItem) => ReactNode | - | Custom row. Read the actions from useFileUpload(). |
FileUploadQueueItem
The default row, a File Card: the type glyph and name, then bytes and time left over a thin bar while it runs, the size and a check when it lands, the error and a frozen red bar with Retry when it fails, the reason when it was never added. Cancel or Remove on every row, named after the file. A failed upload plays the shared shake. Takes every File Card prop except state.
| Prop | Type | Default | Description |
|---|---|---|---|
| item* | FileUploadItem | - | The queue item to render. |
FileUploadSummary
One line under the queue: a spinner with "2 of 3 uploaded · 5.4 of 6.8 MB" while files run, then a check or a warning with the outcome and what was not added. Retry all appears with two or more failed uploads, Clear once anything has settled. Forwards all native <div> props.
useFileUpload
Hook for parts you build yourself inside FileUpload: returns { items, addFiles, retry, remove, clear, openFileDialog }. addFiles takes files from anywhere, a paste handler for one, and runs them through the same validation.
FileUploadGrid
A layout-only grid (2 columns, 3 from sm) for image uploads; fill it with <FileCard layout="tile">. Forwards all native <div> props.