Introduction
Headless React client for S3 upload, download, and delete flows.
@dimah-s3/react is a headless S3 client for React. It manages file intake, validation, progress tracking, retry, cancellation, and multipart transfers — leaving full UI control to you.
Upload and download streams run directly between the browser and the bucket, keeping credentials secure on the server.
Key features
- Headless architecture — Full state management and accessible DOM props without imposing markup or styles.
- Direct-to-bucket transfers — Fast, signed uploads and downloads that bypass your application server.
- Multipart support — Automatic chunking for large files with resumable state via
UploadStore. - Automatic constraint sync — Infers file size and MIME type constraints directly from server route definitions.
- Ready-made UI — Optional accessible shadcn components for instant drop-in controls.
- Backend agnostic — Works seamlessly with
@dimah-s3/serveror any custom API implementingS3Api.
Documentation
Setup
Initialize createS3Client, configure S3Provider, and call your first hook.
Upload
useUpload — single and multi-file uploads with progress tracking.
Download
useDownload — direct downloads and progress streams.
Delete
useDelete — confirm and remove objects through your API.
UI Components
Ready-made shadcn buttons and dropzones built on these hooks.
Upload Store
Persist and resume in-progress multipart uploads across page reloads.
Helpers
Pure utilities for progress formatting, file sizing, and validation.
Forms
Add file uploads to React Hook Form or TanStack Form.
TanStack Query
Invalidate cached records after a confirmed upload.
Custom Backend
Connect the headless hooks to any existing REST or RPC backend.