# React Client (https://v1.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 manages file intake, validation,
progress, retries, cancellation, and multipart transfers while leaving the UI
to you.

Uploads and, by default, downloads run directly between the browser and the
bucket; credentials remain on the server. Downloads can also use the server's
same-origin proxy mode.

## Key features [#key-features]

- **Headless architecture** — Transfer state and accessible DOM props without imposed markup or styles.
- **Presigned transfers** — Uploads and default-mode downloads bypass your application server.
- **Multipart support** — Automatic chunking for large files with resumable state via `UploadStore`.
- **Automatic constraint sync** — Loads file-size and MIME-type constraints from server route definitions.
- **Ready-made UI** — Optional accessible [shadcn components](https://v1.s3.dimah.dev/docs/react/ui) for common file controls.
- **Backend agnostic** — Use `@dimah-s3/server` or a complete custom `S3Api` implementation.

## Documentation [#documentation]

<Cards>
  <Card
    title="React Setup"
    href="/docs/react/setup"
    description="Initialize createS3Client, configure S3Provider, and call your first hook."
  />
  <Card
    title="Upload"
    href="/docs/react/hooks/upload"
    description="useUpload — single and multi-file uploads with progress tracking."
  />
  <Card
    title="Download"
    href="/docs/react/hooks/download"
    description="useDownload — direct downloads and progress streams."
  />
  <Card
    title="Delete"
    href="/docs/react/hooks/delete"
    description="useDelete — confirm and remove objects through your API."
  />
  <Card
    title="Object list"
    href="/docs/react/hooks/object-list"
    description="useObjectList — page a folder catalog from your own query."
  />
  <Card
    title="UI Setup"
    href="/docs/react/ui"
    description="Ready-made shadcn buttons and dropzones built on these hooks."
  />
  <Card
    title="Upload Store"
    href="/docs/react/upload-store"
    description="Persist multipart metadata and resume after the same local file is reselected."
  />
  <Card
    title="Helpers"
    href="/docs/react/helpers"
    description="Pure utilities for progress formatting, file sizing, and validation."
  />
  <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>