Loading…

File Upload

A dropzone over a real file input, plus the upload queue nobody ships.

Forms
2 files
No extra npm packages
Accessibility notes

Playground

Installation

One command and the file is in your project, or copy it in by hand.

$pnpm dlx @dowel-ui/cli add file-upload

No npm packages are needed beyond what Dowel already requires.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { FileUpload } from "@/components/ui/file-upload";

Examples

Every example the tests run, live and operable, side by side.

Default
With Queue
Retries And Failures
Rejected Files Stay Visible
Single File
Disabled
Animated

API

Generated from the component's own types, so a prop cannot appear here without existing.

<FileUpload>

Prop	Type	Default
`label` (required) Names the control.	`string`	—
`onFiles` (required)	`(files: File[]) => void`	—
`accept`	`string`	—
`disabled`	`boolean`	`false`
`hint` Shown under the prompt: accepted types, size limit.	`ReactNode`	—
`icon` A decorative icon above the prompt, hidden from assistive technology. It lifts while a drag is over the dropzone.	`ReactNode`	—
`multiple`	`boolean`	`true`
`children`	`ReactNode`	—

Plus every attribute of <div> except onDrop.

<FileUploadList>

Prop	Type	Default
`files` (required)	`QueuedFile[]`	—
`animateExit` Lets a removed file slide out before it leaves the DOM. The departing row is `aria-hidden`, inert and has no buttons. Off by default, because the old row briefly remains in the markup.	`boolean`	`false`
`onCancel`	`(id: string) => void`	—
`onRemove`	`(id: string) => void`	—
`onRetry`	`(id: string) => void`	—

Plus every attribute of <ul>.

<FileUploadItem>

Prop	Type	Default
`entry` (required)	`QueuedFile`	—
`onCancel`	`(id: string) => void`	—
`onRemove`	`(id: string) => void`	—
`onRetry`	`(id: string) => void`	—

Plus every attribute of <li> except children.

<FileUploadStatus>

Prop	Type	Default
`stats` (required)	`{ total: number; active: number; done: number; failed: number }`	—

Plus every attribute of <p>.

Accessibility

The APG has no dropzone pattern, and inventing one is the usual failure — a div with role="button", a keydown handler, and a picker keyboard users never reach. The control here is a real input[type=file] with a real label, which is already operable, already announced, and opens the picker on Enter and Space with nothing added. Drag and drop is a pointer convenience layered on top; every drop can also be done from the input. Each uploading file gets a progressbar named after it, status is always stated in words as well as drawn, and one polite live region summarises the whole queue rather than six per-file regions talking over each other. The optional dropzone icon is aria-hidden. With animateExit, a removed row lingers only as an aria-hidden, inert copy with no buttons while it animates out.

Quality

Measured from the source and its tests at build time.

All scores

9/10

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — fails
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — passes
No fixed widths — passes

Prop

Type

Default

label

Names the control.

string

—

onFiles

(files: File[]) => void

—

accept

string

—

disabled

boolean

false

hint

Shown under the prompt: accepted types, size limit.

ReactNode

—

icon

A decorative icon above the prompt, hidden from assistive technology. It lifts while a drag is over the dropzone.

ReactNode

—

multiple

boolean

true

children

ReactNode

—

Prop

Type

Default

files

QueuedFile[]

—

animateExit

Lets a removed file slide out before it leaves the DOM. The departing row is aria-hidden, inert and has no buttons. Off by default, because the old row briefly remains in the markup.

boolean

false

onCancel

(id: string) => void

—

onRemove

(id: string) => void

—

onRetry

(id: string) => void

—

Prop

Type

Default

entry

QueuedFile

—

onCancel

(id: string) => void

—

onRemove

(id: string) => void

—

onRetry

(id: string) => void

—

Prop

Type

Default

stats

{ total: number; active: number; done: number; failed: number }

—