Resumable Upload

ProNew

Chunked uploads that survive pauses, dropped connections and page reloads: a useResumableUpload hook with a tus 1.0 adapter, per-chunk retry with backoff, pause and resume from the server's offset, plus a ready card with speed and time left.

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/resumable-upload

Usage

Ready-made card:

Or your own UI with the hook:

Any server works if you write a ResumableAdapter (create, offset, send): for example S3 multipart uploads, where the "offset" is the sum of the parts already stored.

Exports

Export	Description
`useResumableUpload(options)`	`{ state, start(file), pause(), resume(), retry(), cancel() }`.
`ResumableUpload`	File picker and progress card.
`tusAdapter(endpoint, options)`	tus 1.0.0 core protocol over `fetch`.
`SessionGoneError`, `fingerprint`	For your own adapters.

Props

Option	Type	Default	Description
`adapter`	`ResumableAdapter`	-	The server.
`chunkSize`	`number`	5 MiB	Bytes per request.
`retries`, `retryDelay`	`number`	`3`, `1000`	Per chunk; the delay doubles.
`storage`	`Storage \| null`	`localStorage`	Where session ids are kept for a reload. `null` disables it.

state: status (idle, uploading, paused, done, error), progress (0 to 1), offset, total, rate, eta, error, uploadId.

Accessibility

Progress has a name that includes the file; the text line under it (role="status") gives bytes sent, speed and time left, and changes to "Paused at 40%", "Upload complete" or the error (role="alert").
Pause, Resume, Retry and Cancel are real buttons that appear only when they apply. The file picker is a button that opens a hidden input.
The speed and time-left text updates once per chunk, not continuously, so a screen reader is not flooded.

Testing

The component ships with a Testing Library test (resumable-upload.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/resumable-upload

Usage

Ready-made card:

Or your own UI with the hook:

Any server works if you write a ResumableAdapter (create, offset, send): for example S3 multipart uploads, where the "offset" is the sum of the parts already stored.

Exports

Export	Description
`useResumableUpload(options)`	`{ state, start(file), pause(), resume(), retry(), cancel() }`.
`ResumableUpload`	File picker and progress card.
`tusAdapter(endpoint, options)`	tus 1.0.0 core protocol over `fetch`.
`SessionGoneError`, `fingerprint`	For your own adapters.

Props

Option	Type	Default	Description
`adapter`	`ResumableAdapter`	-	The server.
`chunkSize`	`number`	5 MiB	Bytes per request.
`retries`, `retryDelay`	`number`	`3`, `1000`	Per chunk; the delay doubles.
`storage`	`Storage \| null`	`localStorage`	Where session ids are kept for a reload. `null` disables it.

state: status (idle, uploading, paused, done, error), progress (0 to 1), offset, total, rate, eta, error, uploadId.

Accessibility

Progress has a name that includes the file; the text line under it (role="status") gives bytes sent, speed and time left, and changes to "Paused at 40%", "Upload complete" or the error (role="alert").
Pause, Resume, Retry and Cancel are real buttons that appear only when they apply. The file picker is a button that opens a hidden input.
The speed and time-left text updates once per chunk, not continuously, so a screen reader is not flooded.

Testing

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