# React Client (https://v2.s3.dimah.dev/docs/react)

[`@dimah-s3/react`](https://www.npmjs.com/package/@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 [#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 `APIError`s 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](https://v2.s3.dimah.dev/docs/react/ui) built on these hooks.
- **Backend agnostic** — Use `@dimah-s3/server`, or implement the `S3Api` contract yourself.

## Entries [#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 as `uploadFile`, `defineApi`, `memoryObjectSource`, and the stores. Use them in shared or server modules. See [Engine](https://v2.s3.dimah.dev/docs/react/guides/engine).

`APIError`, `S3_ERROR_CODES`, `validateFile`, and the other protocol helpers
come from [`@dimah-s3/core`](https://v2.s3.dimah.dev/docs/core). The React package does not
re-export them. It needs React 19.2.

<Callout>
  Upgrading from 1.7? See [Upgrade to 2.0 beta](https://v2.s3.dimah.dev/docs/migration-2-0) for the
  renamed hooks, callbacks, and entries.
</Callout>

## Documentation [#documentation]

<Cards>
  <Card
    title="React Setup"
    href="/docs/react/setup"
    description="Create the client, mount S3Provider, and call your first hook."
  />
  <Card
    title="Upload"
    href="/docs/react/hooks/upload"
    description="useUpload — a queue of files with progress, cancel, and multipart."
  />
  <Card
    title="Download"
    href="/docs/react/hooks/download"
    description="useDownload hands a URL to the browser; useFetchDownload fetches with progress."
  />
  <Card
    title="Delete"
    href="/docs/react/hooks/delete"
    description="useDelete — remove one or many objects, with state for each key."
  />
  <Card
    title="Object URL"
    href="/docs/react/hooks/object-url"
    description="useObjectUrl — sign, cache, and refresh a URL for a private object."
  />
  <Card
    title="Object list"
    href="/docs/react/hooks/object-list"
    description="useObjectList and useObjectListSelection — page, search, sort, and select a folder catalog."
  />
  <Card
    title="Outcomes and errors"
    href="/docs/react/guides/outcomes"
    description="What actions return, how callbacks run, and how to read errors."
  />
  <Card
    title="Engine"
    href="/docs/react/guides/engine"
    description="Plain functions from @dimah-s3/react/engine, such as uploadFile."
  />
  <Card
    title="UI Setup"
    href="/docs/react/ui"
    description="Ready-made shadcn components built on these hooks."
  />
  <Card
    title="Upload Store"
    href="/docs/react/upload-store"
    description="Persist multipart uploads and resume when the same file is selected again."
  />
  <Card
    title="Helpers"
    href="/docs/react/helpers"
    description="Formatters for sizes, speed, time left, dates, and errors."
  />
  <Card
    title="Forms"
    href="/docs/react/forms"
    description="Add file uploads to React Hook Form or TanStack Form."
  />
  <Card
    title="TanStack Query"
    href="/docs/react/tanstack-query"
    description="Invalidate cached records after a confirmed upload."
  />
  <Card
    title="Bring Your Own Backend"
    href="/docs/react/custom-backend"
    description="Implement the complete S3Api contract for an existing backend."
  />
</Cards>