File Upload

Pro

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.

Drop files here or browse
Images, PDF, XLSX or MOV, up to 25 MB

Try it yourself. This one is live, and its code is right below.

Drop files here or browse
Images, PDF, XLSX or MOV, up to 25 MB

Installation#

# One-time setup (tokens + lib helpers)npx koalaui-cli@latest init# Activate your Pro license (once per machine)npx koalaui-cli@latest login <key># Add this component (its dependencies come along)npx koalaui-cli@latest add file-upload

Usage#

Give File Upload an onUpload and it runs the whole thing: validation, the queue, progress, time left, retry, cancel and an announced outcome.

This example is part of Koala UI Pro

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.

This example is part of Koala UI Pro

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.

Drag and drop your files, or click here

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.

Drop files here or browse
PDF, PNG or JPG, up to 10 MB

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.

Drop images or browse

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.

Drag and drop your files, or click here

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.

Drag and drop your images, or click here
A-frame cabin among autumn trees
Lakeside cabin at dusk
Sunlit forest canopy

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.

KoalaUIFinalDesign.jpg
60%
KoalaUIFinalDesign.jpg
182.2 MB · 60%
KoalaUIFinalDesign.jpg
182.2 MB

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.

No file selected

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.

JC

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.

Drop a PDF here, or click here
Single PDF file, up to 2 MB

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.

comfortable · drop files, or click here
compact · drop files, or click here

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.

Uploads paused
You’ve reached your storage limit

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.

PropTypeDefaultDescription
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 }.
acceptstring-Native input accept, e.g. "image/*,.pdf"; checked against picked and dropped files, and against dragged ones before the drop.
multiplebooleanfalseAllow more than one file per selection; without it, extra files are rejected with "count".
maxSizenumber-Max size per file, in bytes. Larger files are rejected with "size".
disabledbooleanfalseMake 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 attributeDescription
data-disabledPresent 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 attributeDescription
data-draggingPresent 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-disabledPresent 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.

PropTypeDefaultDescription
dragLabelReactNode | ((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.

PropTypeDefaultDescription
variantButtonProps["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.

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

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

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

FAQ#

With onUpload, yes: it keeps the queue, runs your upload per file and hands you every change through onQueueChange. Without it, it owns selection only: accepted files arrive through onFiles and rejections through onReject, and you keep the list.