React Client
Headless React client for S3 upload, download, and delete flows.
@dimah-s3/react is the
headless React client for dimah-s3. It handles file intake, validation,
progress, retries, cancel, and multipart transfers, and leaves the UI to you.
Uploads and, by default, downloads run directly between the browser and the bucket. Credentials stay on the server: the client sends a route name, and the server picks the object key.
Key features
- Per-key state — Each file or object key has its own operation, so lists can show many transfers at once.
- Outcomes, not throws — Every action resolves with an outcome or a result. Errors are
APIErrors with stable codes. - Upload queue — Validated files upload a few at a time, and each can be cancelled on its own.
- Multipart and resume — Large files upload in parts the server lays out, and can resume with an
UploadStore. - Server-owned policy — Accepted types, size limits, multipart, and checksums come from the server's route catalog.
- Ready-made UI — Optional accessible shadcn components built on these hooks.
- Backend agnostic — Use
@dimah-s3/server, or implement theS3Apicontract yourself.
Entries
The package has two entries:
@dimah-s3/react— hooks,S3Provider,createS3Client, the formatter hooks, and types. Its build is marked"use client".@dimah-s3/react/engine— plain functions with no React import, such asuploadFile,defineApi,memoryObjectSource, and the stores. Use them in shared or server modules. See Engine.
APIError, S3_ERROR_CODES, validateFile, and the other protocol helpers
come from @dimah-s3/core. The React package does not
re-export them. It needs React 19.2.
Upgrading from 1.7? See Upgrade to 2.0 beta for the renamed hooks, callbacks, and entries.
Documentation
React Setup
Create the client, mount S3Provider, and call your first hook.
Upload
useUpload — a queue of files with progress, cancel, and multipart.
Download
useDownload hands a URL to the browser; useFetchDownload fetches with progress.
Delete
useDelete — remove one or many objects, with state for each key.
Object URL
useObjectUrl — sign, cache, and refresh a URL for a private object.
Object list
useObjectList and useObjectListSelection — page, search, sort, and select a folder catalog.
Outcomes and errors
What actions return, how callbacks run, and how to read errors.
Engine
Plain functions from @dimah-s3/react/engine, such as uploadFile.
UI Setup
Ready-made shadcn components built on these hooks.
Upload Store
Persist multipart uploads and resume when the same file is selected again.
Helpers
Formatters for sizes, speed, time left, dates, and errors.
Forms
Add file uploads to React Hook Form or TanStack Form.
TanStack Query
Invalidate cached records after a confirmed upload.
Bring Your Own Backend
Implement the complete S3Api contract for an existing backend.