Upload Queue

ProNew

A headless useUploadQueue hook: validates files, uploads with a concurrency limit, tracks per-file and overall progress, retries, cancels and removes, with an XHR uploader that reports real progress.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/upload-queue

Usage

For a signed S3 or R2 URL, pass a function: xhrUploader(async (file) => (await sign(file)).url) and no fieldName, so the file is the raw body of a PUT.

Exports

Export	Description
`useUploadQueue(options)`	Returns `{ items, add, start, cancel, retry, remove, clear, stats }`.
`xhrUploader(url, options)`	An `Uploader` with real upload progress. `url` can be a function that returns a signed URL.
`validateFile`, `matchesAccept`, `formatBytes`	The rules, on their own.

Props

Option	Type	Default	Description
`upload`	`(file, { onProgress, signal }) => Promise<R>`	-	Does the work.
`concurrency`	`number`	`3`	Uploads at once.
`autoStart`	`boolean`	`true`	Otherwise call `start()`.
`accept`, `maxSize`, `minSize`, `maxFiles`			Rules. Broken ones create an item with status `rejected` and a message.
`retries`	`number`	`0`	Extra attempts, with 500 ms, 1 s, 2 s... delays.

Item status: queued, uploading, done, error, canceled, rejected.

Accessibility

The hook renders nothing, so the accessibility comes from your rows. Give each progress bar a name that includes the file (aria-label="Uploading report.pdf"), keep the status text in a live region (role="status") and show item.error in a role="alert".
Rejected files are returned as items, not dropped, so you can tell the person which file failed and why instead of ignoring it.
Cancel, Retry and Remove must be real buttons with the file name in their label.
Uploads abort when the component unmounts, so a closed dialog does not keep sending data.

Testing

The component ships with a Testing Library test (upload-queue.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/upload-queue

Usage

For a signed S3 or R2 URL, pass a function: xhrUploader(async (file) => (await sign(file)).url) and no fieldName, so the file is the raw body of a PUT.

Exports

Export	Description
`useUploadQueue(options)`	Returns `{ items, add, start, cancel, retry, remove, clear, stats }`.
`xhrUploader(url, options)`	An `Uploader` with real upload progress. `url` can be a function that returns a signed URL.
`validateFile`, `matchesAccept`, `formatBytes`	The rules, on their own.

Props

Option	Type	Default	Description
`upload`	`(file, { onProgress, signal }) => Promise<R>`	-	Does the work.
`concurrency`	`number`	`3`	Uploads at once.
`autoStart`	`boolean`	`true`	Otherwise call `start()`.
`accept`, `maxSize`, `minSize`, `maxFiles`			Rules. Broken ones create an item with status `rejected` and a message.
`retries`	`number`	`0`	Extra attempts, with 500 ms, 1 s, 2 s... delays.

Item status: queued, uploading, done, error, canceled, rejected.

Accessibility

The hook renders nothing, so the accessibility comes from your rows. Give each progress bar a name that includes the file (aria-label="Uploading report.pdf"), keep the status text in a live region (role="status") and show item.error in a role="alert".
Rejected files are returned as items, not dropped, so you can tell the person which file failed and why instead of ignoring it.
Cancel, Retry and Remove must be real buttons with the file name in their label.
Uploads abort when the component unmounts, so a closed dialog does not keep sending data.

Testing

The component ships with a Testing Library test (upload-queue.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.