# UploadCN, full documentation

# HTTP (/docs/adapters/http)



```ts
import { httpAdapter } from "@uploadcn/core"

const adapter = httpAdapter<{ id: string; url: string }>({
  url: "/api/files",
  fieldName: "file",
  fields: (item) => ({ folder: String(item.meta.folder ?? "inbox") }),
  headers: async () => ({ authorization: `Bearer ${await getToken()}` }),
})
```

Sends `multipart/form-data` by default; `body: "binary"` sends the raw file with its
MIME type (useful for `PUT` endpoints). The response is parsed as JSON when possible.

<TypeTable
  type="{
  url: { type: &#x22;string | (item) => string&#x22;, required: true },
  method: { type: '&#x22;POST&#x22; | &#x22;PUT&#x22; | &#x22;PATCH&#x22;', default: '&#x22;POST&#x22;' },
  body: { type: '&#x22;multipart&#x22; | &#x22;binary&#x22;', default: '&#x22;multipart&#x22;' },
  fieldName: { type: &#x22;string&#x22;, default: '&#x22;file&#x22;' },
  fields: { type: &#x22;Record<string, string> | (item) => Record<string, string>&#x22; },
  headers: { type: &#x22;Record<string, string> | () => Promise<Record<string, string>>&#x22; },
  withCredentials: { type: &#x22;boolean&#x22;, description: &#x22;Send cookies cross-origin.&#x22; },
  timeout: { type: &#x22;number&#x22;, description: &#x22;Milliseconds.&#x22; },
  parseResponse: { type: &#x22;(response) => TResult&#x22; },
  transport: { type: &#x22;Transport&#x22; },
}"
/>

## Example: Next.js route handler [#example-nextjs-route-handler]

```ts title="app/api/files/route.ts"
export async function POST(request: Request) {
  const form = await request.formData()
  const file = form.get("file") as File
  const url = await saveSomewhere(file)
  return Response.json({ url })
}
```

Proxying files through your server is simple but costs bandwidth and is limited by
platform body-size limits (4.5 MB on Vercel functions). Prefer
[presigned uploads](/docs/guides/presigned-uploads) for large files.


---

# Adapters (/docs/adapters)



An adapter is a plain object with an `upload` function. The engine handles queueing,
retries, pause/cancel, progress throttling, speed and persistence; the adapter only
moves bytes and reports progress.

```ts
interface UploadAdapter<TResult> {
  name: string
  /** Pausing is offered only for resumable uploads. */
  resumable?: boolean | ((file: File) => boolean)
  upload(context: UploadAdapterContext): Promise<TResult>
  /** Clean up server state (e.g. abort a multipart upload) on cancel. */
  abort?(context: { item; resumeState }): Promise<void>
}
```

## Built-in adapters [#built-in-adapters]

| Adapter                                        | For                                                           |
| ---------------------------------------------- | ------------------------------------------------------------- |
| [`s3Adapter`](/docs/adapters/s3)               | S3 and S3-compatible storage, single PUT or multipart         |
| [`r2Adapter`](/docs/adapters/r2)               | Cloudflare R2 (alias of `s3Adapter`)                          |
| [`presignedAdapter`](/docs/adapters/presigned) | Any service that issues signed URLs or POST policies          |
| [`multipartAdapter`](/docs/adapters/multipart) | Any chunked protocol: bring create / uploadPart / complete    |
| [`httpAdapter`](/docs/adapters/http)           | A plain endpoint that accepts files                           |
| [`tusAdapter`](/docs/adapters/tus)             | tus servers (tusd, @tus/server, Supabase, Cloudflare Stream…) |
| [`mockAdapter`](/docs/adapters/mock)           | Prototypes, tests and docs                                    |
| `routeAdapter`                                 | Pick an adapter per file                                      |

```ts
import { MiB, httpAdapter, routeAdapter } from "@uploadcn/core"
import { tusAdapter } from "@uploadcn/core/tus"

const adapter = routeAdapter((file) =>
  file.size > 100 * MiB ? tusAdapter({ endpoint: "/files" }) : httpAdapter({ url: "/upload" })
)
```

## Writing your own [#writing-your-own]

The context gives you everything you need:

```ts
interface UploadAdapterContext {
  item: UploadItem
  file: File                       // after transforms
  signal: AbortSignal              // aborted on pause, cancel and remove
  attempt: number                  // 1-based, within the current run
  resumeState: unknown             // what you saved last time
  onProgress(loaded: number, total?: number): void
  onChunkProgress(completed: number, total: number): void
  saveResumeState(state: unknown): void
}
```

Throw an [`UploadError`](/docs/reference/core#uploaderror) with `retryable: true` for
failures worth retrying.

### Supabase Storage [#supabase-storage]

```ts
import { presignedAdapter } from "@uploadcn/core"

export const supabaseAdapter = presignedAdapter({
  async getTarget({ file }) {
    // Your route calls supabase.storage.from(bucket).createSignedUploadUrl(path)
    const { signedUrl, path } = await fetch("/api/supabase-upload", {
      method: "POST",
      body: JSON.stringify({ name: file.name }),
    }).then((res) => res.json())
    return { url: signedUrl, key: path }
  },
})
```

### Firebase Storage [#firebase-storage]

```ts
import { UploadError, type UploadAdapter } from "@uploadcn/core"
import { getStorage, ref, uploadBytesResumable, getDownloadURL } from "firebase/storage"

export const firebaseAdapter: UploadAdapter<{ path: string; url: string }> = {
  name: "firebase",
  upload: ({ file, signal, onProgress }) =>
    new Promise((resolve, reject) => {
      const path = `uploads/${crypto.randomUUID()}-${file.name}`
      const task = uploadBytesResumable(ref(getStorage(), path), file)
      signal.addEventListener("abort", () => task.cancel())
      task.on(
        "state_changed",
        (snapshot) => onProgress(snapshot.bytesTransferred, snapshot.totalBytes),
        (error) => reject(new UploadError(error.message, { code: "network", retryable: true })),
        async () => resolve({ path, url: await getDownloadURL(task.snapshot.ref) })
      )
    }),
}
```

### Azure Blob Storage and Google Cloud Storage [#azure-blob-storage-and-google-cloud-storage]

Both issue signed URLs from your server (SAS tokens / V4 signed URLs), so they work
with [`presignedAdapter`](/docs/adapters/presigned). For very large files, use
[`multipartAdapter`](/docs/adapters/multipart) with Azure's Put Block / Put Block List
or GCS's XML multipart API.

### UploadThing [#uploadthing]

UploadThing ships its own React client. If you want UploadCN's UI on top of it, wrap
its `uploadFiles` helper in an adapter's `upload` function and forward `onUploadProgress`
to `onProgress`.


---

# Mock (/docs/adapters/mock)



<ComponentPreview name="error-states" />

`mockAdapter` simulates throughput, latency, chunks, failures and resume, so you can
build and test every UI state before your backend exists.

```ts
import { MiB, UploadError, mockAdapter } from "@uploadcn/core"

const adapter = mockAdapter({
  speed: 2 * MiB,          // bytes per second
  latency: 250,            // ms before the first byte
  chunkSize: 5 * MiB,      // report chunk progress
  resumable: true,         // pause continues from the last byte
  failureRate: 0.1,        // 10% of attempts fail midway (retryable)
  fail: ({ file, attempt }) =>
    file.name.includes("forbidden")
      ? new UploadError("Forbidden", { code: "http", status: 403 })
      : null,
})
```

Results look like `{ key, url: "mock://uploads/…" }`.

## In tests [#in-tests]

The engine is plain TypeScript, so you can drive it from Vitest without a DOM:

```ts
const uploader = createUploader({ adapter: mockAdapter({ latency: 0, speed: 1e9 }), network: false })
const [item] = await uploader.add([new File(["hello"], "a.txt")])
await vi.waitFor(() => expect(uploader.getItem(item.id)?.status).toBe("success"))
```


---

# Multipart & chunked (/docs/adapters/multipart)



<ComponentPreview name="chunked-upload" />

`multipartAdapter` splits files into parts, uploads them in parallel, retries failed
parts independently, reports aggregate and chunk progress, and records finished parts
so uploads resume after a pause, a network loss, or a page reload.

You bring three functions; it works with S3's multipart API, GCS's XML API, Azure
block blobs, or your own chunk endpoint.

```ts
import { multipartAdapter, MiB } from "@uploadcn/core"

const adapter = multipartAdapter({
  partSize: 8 * MiB,
  concurrency: 4,
  retry: { retries: 3, baseDelay: 500 },
  create: ({ file }) => api.createUpload(file),                 // → session
  uploadPart: ({ session, partNumber, blob, signal, onProgress }) =>
    api.putPart(session, partNumber, blob, { signal, onProgress }), // → { etag }
  complete: ({ session, parts }) => api.complete(session, parts),    // → result
  abort: ({ session }) => api.abort(session),
  listParts: ({ session }) => api.listParts(session),           // optional
})
```

## Options [#options]

<TypeTable
  type="{
  partSize: { type: &#x22;number | (fileSize) => number&#x22;, default: &#x22;8 MiB&#x22; },
  minPartSize: { type: &#x22;number&#x22;, default: &#x22;5 MiB&#x22;, description: &#x22;Smallest part except the last (S3 limit).&#x22; },
  maxParts: { type: &#x22;number&#x22;, default: &#x22;10 000&#x22;, description: &#x22;Part size grows automatically to stay under this.&#x22; },
  concurrency: { type: &#x22;number&#x22;, default: &#x22;4&#x22;, description: &#x22;Parts in flight per file.&#x22; },
  retry: { type: &#x22;RetryOptions | false&#x22;, default: &#x22;3 retries from 500 ms&#x22;, description: &#x22;Per-part retry policy.&#x22; },
  create: { type: &#x22;(ctx) => Promise<TSession>&#x22;, required: true, description: &#x22;Session must be JSON-serializable (it's persisted).&#x22; },
  uploadPart: { type: &#x22;(ctx) => Promise<{ etag }>&#x22;, required: true },
  complete: { type: &#x22;(ctx) => Promise<TResult>&#x22;, required: true },
  abort: { type: &#x22;(ctx) => Promise<void>&#x22;, description: &#x22;Called when the user cancels or removes the item.&#x22; },
  listParts: { type: &#x22;(ctx) => Promise<UploadedPart[] | null>&#x22;, description: &#x22;Server truth on resume; return null to keep local state.&#x22; },
}"
/>

## Resume state [#resume-state]

After each finished part the adapter saves:

```ts
{ session, partSize, fileSize, parts: [{ partNumber, etag, size }] }
```

With [persistence](/docs/guides/resumable-uploads), this survives reloads. When the
saved state doesn't match the file (different size or part size), the upload starts
over cleanly.

## Retries at two levels [#retries-at-two-levels]

1. A failed **part** is retried with backoff without touching other parts.
2. If a part exhausts its retries, the **item** fails; the engine's own retry policy
   then retries the item, which resumes from the parts already stored.


---

# Presigned URLs (/docs/adapters/presigned)



`presignedAdapter` implements the generic presigned flow for any provider: Google Cloud
Storage V4 signed URLs, Azure SAS URLs, Supabase signed upload URLs, S3 POST policies,
or your own signing service.

<Flow
  label="Presigned upload"
  steps="[
  &#x22;Select&#x22;,
  &#x22;Validate&#x22;,
  { label: &#x22;getTarget()&#x22;, note: &#x22;your backend signs&#x22; },
  { label: &#x22;PUT / POST&#x22;, note: &#x22;browser → storage&#x22;, highlight: true },
  &#x22;Progress&#x22;,
  &#x22;Done&#x22;,
  { label: &#x22;complete()&#x22;, note: &#x22;optional&#x22; },
]"
/>

```ts
import { presignedAdapter } from "@uploadcn/core"

const adapter = presignedAdapter({
  async getTarget({ file, signal }) {
    const response = await fetch("/api/sign", {
      method: "POST",
      body: JSON.stringify({ name: file.name, type: file.type, size: file.size }),
      signal,
    })
    return response.json() // { url, method?, headers?, fields?, key?, publicUrl? }
  },
  async complete({ target, file }) {
    const response = await fetch("/api/files", {
      method: "POST",
      body: JSON.stringify({ key: target.key, name: file.name }),
    })
    return response.json()
  },
})
```

## Target [#target]

<TypeTable
  type="{
  url: { type: &#x22;string&#x22;, required: true },
  method: { type: '&#x22;PUT&#x22; | &#x22;POST&#x22;', default: '&#x22;PUT&#x22;', description: &#x22;POST sends a multipart form (S3 POST policy).&#x22; },
  headers: { type: &#x22;Record<string, string>&#x22;, description: &#x22;Headers that were signed and must be sent as-is.&#x22; },
  fields: { type: &#x22;Record<string, string>&#x22;, description: &#x22;POST policy form fields, sent before the file.&#x22; },
  key: { type: &#x22;string&#x22;, description: &#x22;Object key, returned in the result.&#x22; },
  publicUrl: { type: &#x22;string&#x22;, description: &#x22;Readable URL, returned in the result.&#x22; },
}"
/>

Without `complete`, the result is `{ key, url }` (the URL without its signature query).

For S3 and R2 you don't need to write the signing route yourself, use
[`s3Adapter`](/docs/adapters/s3) with `@uploadcn/server`.


---

# Cloudflare R2 (/docs/adapters/r2)



<ComponentPreview name="r2-presigned" />

R2 implements the S3 API, so the browser code is identical to S3, `r2Adapter` is an
alias of `s3Adapter`. The difference is on the server.

## Server [#server]

```ts title="app/api/upload/route.ts"
import { createUploadRoute, r2Storage } from "@uploadcn/server"

export const { POST } = createUploadRoute({
  storage: r2Storage({
    accountId: process.env.R2_ACCOUNT_ID!,
    bucket: process.env.R2_BUCKET!,
    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
    // A custom domain or r2.dev URL for reading objects:
    publicUrl: process.env.R2_PUBLIC_URL,
  }),
})
```

`r2Storage` uses `https://<account>.r2.cloudflarestorage.com`, region `auto` and
path-style URLs. For jurisdiction-restricted buckets pass `jurisdiction: "eu"`.

`@uploadcn/server` signs with Web Crypto, so the same route runs on Cloudflare Workers.

## CORS [#cors]

In the R2 dashboard, under **Settings → CORS policy**:

```json
[
  {
    "AllowedOrigins": ["https://your-app.com"],
    "AllowedMethods": ["PUT"],
    "AllowedHeaders": ["content-type"],
    "ExposeHeaders": ["ETag"]
  }
]
```

## Client [#client]

```ts
import { r2Adapter } from "@uploadcn/core"

const adapter = r2Adapter({ endpoint: "/api/upload" })
```


---

# Amazon S3 (/docs/adapters/s3)



<ComponentPreview name="s3-presigned" />

## How it works [#how-it-works]

1. The browser validates the file and asks your route for a signed URL.
2. The route checks auth, size and type, and signs a `PUT` whose signature locks the
   **content type and content length**: S3 rejects anything else.
3. The browser uploads directly to the bucket and tracks progress.
4. The browser calls `complete`; the route verifies the object with `HEAD` and runs
   `onUploadComplete` (save metadata, enqueue a scan…).

Files at or above `multipart.threshold` (64 MB by default) use S3 multipart instead:
parts are signed one at a time, uploaded in parallel, retried individually, and the
upload can pause, resume, and survive reloads.

## Client [#client]

```ts
import { MiB, s3Adapter } from "@uploadcn/core"

const adapter = s3Adapter({
  endpoint: "/api/upload",
  multipart: { threshold: 64 * MiB, partSize: 8 * MiB, concurrency: 4 },
  headers: async () => ({ authorization: `Bearer ${await getToken()}` }),
})
```

<TypeTable
  type="{
  endpoint: { type: &#x22;string&#x22;, required: true, description: &#x22;Your upload route.&#x22; },
  multipart: { type: &#x22;{ threshold?, partSize?, concurrency? } | false&#x22;, description: &#x22;Multipart settings, or false to always use one PUT.&#x22; },
  headers: { type: &#x22;Record<string, string> | () => Promise<Record<string, string>>&#x22;, description: &#x22;Sent to your route (not to S3).&#x22; },
  credentials: { type: &#x22;RequestCredentials&#x22;, description: &#x22;fetch credentials mode for your route.&#x22; },
  fetch: { type: &#x22;typeof fetch&#x22; },
  transport: { type: &#x22;Transport&#x22;, description: &#x22;Replace the XHR transport (tests, instrumentation).&#x22; },
}"
/>

The result is a `StoredObject`: `{ key, url, etag?, data? }`.

## Server [#server]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add @uploadcn/upload-route
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @uploadcn/upload-route
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @uploadcn/upload-route
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add @uploadcn/upload-route
    ```
  </CodeBlockTab>
</CodeBlockTabs>

```ts title="app/api/upload/route.ts"
import { UploadRouteError, createUploadRoute, s3Storage } from "@uploadcn/server"

import { auth } from "@/lib/auth"
import { db } from "@/lib/db"

export const { POST } = createUploadRoute({
  storage: s3Storage({
    bucket: process.env.S3_BUCKET!,
    region: process.env.S3_REGION!,
    accessKeyId: process.env.S3_ACCESS_KEY_ID!,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
  }),
  maxFileSize: 500 * 1024 * 1024,
  allowedTypes: ["image/*", "application/pdf"],
  async authorize({ key }) {
    const session = await auth()
    if (!session) throw new UploadRouteError("Unauthorized", 401)
    // Multipart actions carry the key: make sure it's the caller's.
    if (key && !key.startsWith(`${session.user.id}/`)) throw new UploadRouteError("Forbidden", 403)
    return session.user
  },
  getKey: ({ auth, file }) => `${auth.id}/${crypto.randomUUID()}/${file.name}`,
  async onUploadComplete({ auth, key, file }) {
    return db.file.create({ data: { userId: auth.id, key, name: file.name, size: file.size } })
  },
})
```

See the [server reference](/docs/reference/server) for every option.

## Bucket CORS [#bucket-cors]

```json
[
  {
    "AllowedOrigins": ["https://your-app.com"],
    "AllowedMethods": ["PUT"],
    "AllowedHeaders": ["content-type"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3600
  }
]
```

`ExposeHeaders: ["ETag"]` is required for multipart uploads: the browser reads each
part's ETag to complete the upload.

## S3-compatible services [#s3-compatible-services]

Pass `endpoint` to `s3Storage` for MinIO, Backblaze B2, DigitalOcean Spaces, Wasabi
and others. Path-style URLs are used automatically with a custom endpoint.

```ts
s3Storage({
  endpoint: "https://s3.us-west-004.backblazeb2.com",
  region: "us-west-004",
  bucket: "uploads",
  accessKeyId: process.env.B2_KEY_ID!,
  secretAccessKey: process.env.B2_APPLICATION_KEY!,
})
```

## Abandoned multipart uploads [#abandoned-multipart-uploads]

Parts of cancelled uploads are aborted automatically. Parts of uploads that are simply
abandoned (tab closed, never resumed) are billed until removed, add a bucket lifecycle
rule to abort incomplete multipart uploads after a few days.


---

# tus (/docs/adapters/tus)



[tus](https://tus.io) is an open protocol for resumable uploads, supported by tusd,
`@tus/server`, Supabase Storage, Cloudflare Stream, Vimeo and others. UploadCN wraps
the reference client, `tus-js-client`, rather than reimplementing the protocol.

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install tus-js-client
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add tus-js-client
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add tus-js-client
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add tus-js-client
    ```
  </CodeBlockTab>
</CodeBlockTabs>

```ts
import { tusAdapter } from "@uploadcn/core/tus"

const adapter = tusAdapter({
  endpoint: "https://tusd.example.com/files/",
  chunkSize: 8 * 1024 * 1024,
  headers: async () => ({ authorization: `Bearer ${await getToken()}` }),
  metadata: { bucket: "videos" },
})
```

The engine stores the tus upload URL as resume state, so it works with
[IndexedDB persistence](/docs/guides/resumable-uploads) across reloads (tus-js-client's
own localStorage fingerprinting is turned off). Cancelling an upload sends a tus
termination request.

<TypeTable
  type="{
  endpoint: { type: &#x22;string&#x22;, required: true },
  chunkSize: { type: &#x22;number&#x22;, description: &#x22;Bytes per PATCH request.&#x22; },
  parallelUploads: { type: &#x22;number&#x22;, description: &#x22;Requires the concatenation extension on the server.&#x22; },
  retryDelays: { type: &#x22;number[]&#x22;, default: &#x22;[]&#x22;, description: &#x22;tus-js-client's own retries. Off by default: the engine retries.&#x22; },
  headers: { type: &#x22;Record<string, string> | () => Promise<Record<string, string>>&#x22; },
  metadata: { type: &#x22;Record<string, string>&#x22;, description: &#x22;filename and filetype are always sent.&#x22; },
}"
/>


---

# Animated Queue (/docs/components/animated-upload-queue)



<ComponentPreview name="animated-upload-queue" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/animated-upload-queue
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/animated-upload-queue
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/animated-upload-queue
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/animated-upload-queue
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="animated-upload-queue" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { AnimatedUploadQueue } from "@/components/animated-upload-queue"
```

```tsx
<AnimatedUploadQueue maxFiles={20} />
```

Built from the same `UploadItem` parts as the static queue, wrapped in `AnimatePresence` for exit animations.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
}"
/>


---

# Assignment Submission (/docs/components/assignment-submission)



<ComponentPreview name="assignment-submission" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/assignment-submission
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/assignment-submission
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/assignment-submission
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/assignment-submission
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and the shadcn `badge`, `button` components, then copy:

    <ComponentSource name="assignment-submission" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { AssignmentSubmission } from "@/components/assignment-submission"
```

```tsx
<AssignmentSubmission
  title="Essay: The Industrial Revolution"
  due={new Date("2026-11-01T23:59:00")}
  onSubmit={(files) => turnIn(files)}
/>
```

The countdown renders on the client only, so server and client HTML always match.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  course: { type: &#x22;string&#x22; },
  title: { type: &#x22;string&#x22; },
  due: { type: &#x22;Date&#x22;, description: &#x22;Required.&#x22; },
  points: { type: &#x22;number&#x22;, default: &#x22;100&#x22; },
  accept: { type: &#x22;string&#x22; },
  onSubmit: { type: &#x22;(files) => void | Promise<void>&#x22; },
  onUnsubmit: { type: &#x22;() => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Audio Upload (/docs/components/audio-upload)



<ComponentPreview name="audio-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/audio-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/audio-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/audio-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/audio-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) first, then copy:

    <ComponentSource name="audio-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { AudioUpload } from "@/components/audio-upload"
```

```tsx
<AudioUpload maxDuration={3600} />
```

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  maxDuration: {
    type: &#x22;number&#x22;,
    description: &#x22;Longest allowed recording, in seconds.&#x22;,
  },
  maxFiles: { type: &#x22;number&#x22;, default: &#x22;10&#x22; },
  maxSize: { type: &#x22;number&#x22;, default: &#x22;500 MB&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
}"
/>


---

# Avatar Upload (/docs/components/avatar-upload)



<ComponentPreview name="avatar-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/avatar-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/avatar-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/avatar-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/avatar-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) first, then copy:

    <ComponentSource name="avatar-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { AvatarUpload } from "@/components/avatar-upload"
```

```tsx
<AvatarUpload
  src={user.image}
  onChange={(item) => updateUser({ image: item?.result?.url ?? null })}
/>
```

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  src: { type: &#x22;string | null&#x22;, description: &#x22;The current avatar URL.&#x22; },
  size: {
    type: &#x22;number&#x22;,
    default: &#x22;512&#x22;,
    description: &#x22;Output size in pixels (square, WebP).&#x22;,
  },
  onChange: {
    type: &#x22;(item | null) => void&#x22;,
    description: &#x22;Called after upload, or with null on removal.&#x22;,
  },
  name: { type: &#x22;string&#x22;, description: &#x22;Form field name.&#x22; },
}"
/>


---

# Battery (/docs/components/battery-upload)



<ComponentPreview name="battery-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/battery-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/battery-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/battery-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/battery-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="battery-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { BatteryUpload } from "@/components/battery-upload"
```

```tsx
<BatteryUpload noun="photos" />
```

Five cells share one spring, each filling its fifth of the progress. Failed uploads turn the cells destructive. The caption is an `aria-live` region with counts, bytes and time left.

It uploads through your [adapter](/docs/storage) like every other component, so it works with S3, R2, Cloudinary, local disk or your own API.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    description:
      &#x22;Where files go. Defaults to the UploadConfigProvider adapter.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22;, default: '[&#x22;image/*&#x22;, &#x22;video/*&#x22;]' },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  noun: {
    type: &#x22;string&#x22;,
    default: '&#x22;files&#x22;',
    description: &#x22;What is being backed up, used in the caption.&#x22;,
  },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Blueprint (/docs/components/blueprint-upload)



<ComponentPreview name="blueprint-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/blueprint-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/blueprint-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/blueprint-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/blueprint-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="blueprint-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { BlueprintUpload } from "@/components/blueprint-upload"
```

```tsx
<BlueprintUpload project="Riverside Library" />
```

Each line of the drawing takes its share of the progress, so the building is drafted in order. A dashed ghost keeps the sheet readable before anything uploads. The title block lists the latest sheet, file count and size.

It uploads through your [adapter](/docs/storage) like every other component, so it works with S3, R2, Cloudinary, local disk or your own API.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    description:
      &#x22;Where files go. Defaults to the UploadConfigProvider adapter.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: {
    type: &#x22;string | string[]&#x22;,
    default:
      '[&#x22;.pdf&#x22;, &#x22;.dwg&#x22;, &#x22;.dxf&#x22;, &#x22;.ifc&#x22;, &#x22;.step&#x22;, &#x22;.stl&#x22;, &#x22;.svg&#x22;, &#x22;image/*&#x22;]',
  },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  project: {
    type: &#x22;string&#x22;,
    default: '&#x22;Project A-104&#x22;',
    description: &#x22;Project name in the title block.&#x22;,
  },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Camera Upload (/docs/components/camera-upload)



<ComponentPreview name="camera-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/camera-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/camera-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/camera-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/camera-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload), then copy:

    <ComponentSource name="camera-upload" />

    <ComponentSource name="use-camera" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { CameraUpload } from "@/components/camera-upload"
```

```tsx
<CameraUpload facingMode="user" maxFiles={5} />
```

`CameraCapture` is exported too, drop it inside any `<Upload>` to add a viewfinder. The [`useCamera`](#usecamera) hook releases the camera on unmount.

## useCamera [#usecamera]

The hook behind the viewfinder. It's installed with the component.

```tsx
const { videoRef, status, start, stop, flip, capture } = useCamera()

<video ref={videoRef} muted playsInline />
<button onClick={() => start()}>Open camera</button>
<button onClick={async () => uploader.add([await capture()])}>Snap</button>
```

`status` is `idle`, `starting`, `ready`, `denied`, `unavailable` or `error`.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  maxFiles: { type: &#x22;number&#x22;, default: &#x22;10&#x22; },
  facingMode: { type: '&#x22;user&#x22; | &#x22;environment&#x22;', default: '&#x22;environment&#x22;' },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Chat Attachments (/docs/components/chat-attachments)



<ComponentPreview name="chat-attachment" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/chat-attachments
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/chat-attachments
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/chat-attachments
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/chat-attachments
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) first, then copy:

    <ComponentSource name="chat-attachments" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { ChatAttachments } from "@/components/chat-attachments"
```

```tsx
<ChatAttachments
  onSend={async ({ text, attachments }) => {
    await sendMessage({ text, files: attachments.map((item) => item.result) })
  }}
/>
```

Images are downscaled to 1568px WebP before upload (the size vision models work with), which makes attachments upload several times faster. Paste is scoped to the composer.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  onSend: {
    type: &#x22;({ text, attachments }) => void | Promise<void>&#x22;,
    description: &#x22;Called on Enter or the send button, once uploads finished.&#x22;,
  },
  placeholder: { type: &#x22;string&#x22; },
  accept: {
    type: &#x22;string[]&#x22;,
    default: &#x22;images, PDF, text, Markdown, CSV, JSON, DOCX&#x22;,
  },
  maxFiles: { type: &#x22;number&#x22;, default: &#x22;10&#x22; },
  maxSize: { type: &#x22;number&#x22;, default: &#x22;25 MB&#x22; },
  disabled: { type: &#x22;boolean&#x22; },
}"
/>


---

# Cloud Dropzone (/docs/components/cloud-dropzone)



<ComponentPreview name="cloud-dropzone" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/cloud-dropzone
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/cloud-dropzone
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/cloud-dropzone
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/cloud-dropzone
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="cloud-dropzone" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { CloudDropzone } from "@/components/cloud-dropzone"
```

```tsx
<CloudDropzone maxSize={100 * 1000 * 1000} />
```

The fill is an SVG clip path driven by `useUploadProgress`.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
  showQueue: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22; },
}"
/>


---

# CSV Import (/docs/components/csv-import)



<ComponentPreview name="csv-import" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/csv-import
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/csv-import
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/csv-import
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/csv-import
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and the shadcn `badge`, `button`, `table` components, then copy:

    <ComponentSource name="csv-import" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { CsvImport } from "@/components/csv-import"
```

```tsx
<CsvImport
  columns={[
    { key: "email", label: "Email", required: true },
    { key: "name", label: "Name" },
  ]}
  onSuccess={(item, preview) => startImportJob(item.result, preview.rowCount)}
/>
```

Uploading only starts when the user clicks **Import**, and stays disabled while required columns are missing. Parsing is a small RFC 4180 parser, swap in Papa Parse for exotic files.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  columns: {
    type: &#x22;CsvColumn[]&#x22;,
    default: &#x22;a product catalog&#x22;,
    description:
      &#x22;`{ key, label?, required? }`. Headers match case- and space-insensitively.&#x22;,
  },
  maxSize: { type: &#x22;number&#x22;, default: &#x22;50 MB&#x22; },
  onSuccess: { type: &#x22;(item, preview) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Delivery (/docs/components/delivery-upload)



<ComponentPreview name="delivery-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/delivery-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/delivery-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/delivery-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/delivery-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="delivery-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { DeliveryUpload } from "@/components/delivery-upload"
```

```tsx
<DeliveryUpload destination="Warehouse 4" />
```

The truck's position is a spring on the overall percent, and the road markings and wheels only move while it's driving. The status line says where the files are going and when they'll arrive.

It uploads through your [adapter](/docs/storage) like every other component, so it works with S3, R2, Cloudinary, local disk or your own API.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    description:
      &#x22;Where files go. Defaults to the UploadConfigProvider adapter.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  destination: {
    type: &#x22;string&#x22;,
    default: '&#x22;Head office&#x22;',
    description: &#x22;Where the files are going, shown in the status.&#x22;,
  },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Document Checklist (/docs/components/document-checklist)



<ComponentPreview name="document-checklist" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/document-checklist
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/document-checklist
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/document-checklist
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/document-checklist
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and the shadcn `badge` component, then copy:

    <ComponentSource name="document-checklist" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { DocumentChecklist } from "@/components/document-checklist"
```

```tsx
<DocumentChecklist
  title="Onboarding documents"
  items={[
    {
      name: "contract",
      label: "Signed contract",
      accept: "application/pdf",
      required: true,
    },
    { name: "tax-form", label: "Tax form", required: true },
    { name: "photo", label: "Profile photo", accept: "image/*" },
  ]}
/>
```

Each file carries its requirement name in `item.meta.slot`, so your backend knows which document is which.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  title: { type: &#x22;string&#x22;, default: '&#x22;Supporting documents&#x22;' },
  description: { type: &#x22;string&#x22; },
  items: {
    type: &#x22;ChecklistItem[]&#x22;,
    default: &#x22;an insurance claim&#x22;,
    description: &#x22;`{ name, label, description?, accept?, required? }`&#x22;,
  },
  maxSize: { type: &#x22;number&#x22;, default: &#x22;25 MB&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Document Ingest (/docs/components/document-ingest)



<ComponentPreview name="ai-document-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/document-ingest
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/document-ingest
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/document-ingest
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/document-ingest
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) first, then copy:

    <ComponentSource name="document-ingest" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { DocumentIngest } from "@/components/document-ingest"
```

```tsx
<DocumentIngest
  ingest={async (item, { setStage, signal }) => {
    const { jobId } = await startIngestion(item.result.key, { signal })
    for await (const stage of watchJob(jobId, { signal })) setStage(stage)
  }}
/>
```

Stages are `upload`, `parse`, `chunk`, `embed` and `index`. Report them from polling, server-sent events or webhooks: the UI only reflects what your backend says.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  ingest: {
    type: &#x22;(item, { setStage, signal, setStatus, result }) => Promise<void>&#x22;,
    description:
      &#x22;Drives server-side ingestion after the bytes are stored. Throw to fail the item.&#x22;,
  },
  accept: {
    type: &#x22;string[]&#x22;,
    default: &#x22;PDF, DOCX, TXT, MD, HTML, CSV, JSON&#x22;,
  },
  maxFiles: { type: &#x22;number&#x22;, default: &#x22;50&#x22; },
}"
/>


---

# Document Upload (/docs/components/document-upload)



<ComponentPreview name="document-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/document-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/document-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/document-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/document-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) first, then copy:

    <ComponentSource name="document-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { DocumentUpload } from "@/components/document-upload"
```

```tsx
<DocumentUpload variant="resume" name="resume" />
```

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  variant: {
    type: '&#x22;documents&#x22; | &#x22;pdf&#x22; | &#x22;resume&#x22;',
    default: '&#x22;documents&#x22;',
    description:
      &#x22;Preset for accepted types, limits and copy. `resume` is a single PDF/Word file.&#x22;,
  },
  maxFiles: { type: &#x22;number&#x22; },
  maxSize: { type: &#x22;number&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Form field name.&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
}"
/>

## Examples [#examples]

### PDF [#pdf]

<ComponentPreview name="pdf-upload" />


---

# Envelope (/docs/components/envelope-upload)



<ComponentPreview name="envelope-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/envelope-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/envelope-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/envelope-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/envelope-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="envelope-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { EnvelopeUpload } from "@/components/envelope-upload"
```

```tsx
<EnvelopeUpload recipient="Acme Legal" accept="application/pdf" />
```

The flap is a 3D `rotateX` and the seal uses a spring. With reduced motion, states change instantly.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
  recipient: { type: &#x22;string&#x22;, default: '&#x22;Acme Legal&#x22;' },
}"
/>


---

# File Upload (/docs/components/file-upload)



<ComponentPreview name="basic-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/file-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/file-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/file-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/file-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) first, then copy:

    <ComponentSource name="file-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { FileUpload } from "@/components/file-upload"
```

```tsx
<FileUpload
  accept="image/*,application/pdf"
  maxSize={20_000_000}
  maxFiles={10}
/>
```

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  accept: {
    type: &#x22;string | string[]&#x22;,
    description: &#x22;Accepted types: MIME types, wildcards or extensions.&#x22;,
  },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Max size per file, in bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  image: {
    type: &#x22;ImageConstraints&#x22;,
    description: &#x22;Min/max image dimensions.&#x22;,
  },
  media: {
    type: &#x22;MediaConstraints&#x22;,
    description: &#x22;Min/max audio/video duration.&#x22;,
  },
  autoUpload: {
    type: &#x22;boolean&#x22;,
    default: &#x22;true&#x22;,
    description: &#x22;When false, files wait for the Upload button.&#x22;,
  },
  multiple: { type: &#x22;boolean&#x22; },
  disabled: { type: &#x22;boolean&#x22; },
  title: { type: &#x22;ReactNode&#x22; },
  description: {
    type: &#x22;ReactNode&#x22;,
    description: &#x22;Defaults to a summary of the limits.&#x22;,
  },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  onComplete: {
    type: &#x22;(items) => void&#x22;,
    description: &#x22;Called when the queue drains.&#x22;,
  },
}"
/>

## Examples [#examples]

### Multiple files [#multiple-files]

<ComponentPreview name="multiple-upload" />

### Batch upload [#batch-upload]

<ComponentPreview name="batch-upload" />

### S3 presigned [#s3-presigned]

<ComponentPreview name="s3-presigned" />


---

# Flip Card (/docs/components/flip-card-upload)



<ComponentPreview name="flip-card-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/flip-card-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/flip-card-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/flip-card-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/flip-card-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="flip-card-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { FlipCardUpload } from "@/components/flip-card-upload"
```

```tsx
<FlipCardUpload title="Upload your contract" accept="application/pdf" />
```

The hidden face is `inert`, so keyboard focus never lands on the side you can't see.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  title: { type: &#x22;string&#x22;, default: '&#x22;Upload your file&#x22;' },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Folder Upload (/docs/components/folder-upload)



<ComponentPreview name="folder-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/folder-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/folder-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/folder-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/folder-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="folder-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { FolderUpload } from "@/components/folder-upload"
```

```tsx
<FolderUpload name="Q3 Reports" maxFiles={20} />
```

The folder opens with CSS on hover and while dragging (`group-data-dragging`), and the flying files use `motion`. With `prefers-reduced-motion`, files don't fly and the folder doesn't tilt.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  name: {
    type: &#x22;string&#x22;,
    default: '&#x22;Uploads&#x22;',
    description: &#x22;Text on the folder tab.&#x22;,
  },
  title: { type: &#x22;ReactNode&#x22; },
  description: { type: &#x22;ReactNode&#x22; },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  onComplete: { type: &#x22;(items) => void&#x22; },
}"
/>


---

# Gallery Upload (/docs/components/gallery-upload)



<ComponentPreview name="gallery-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/gallery-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/gallery-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/gallery-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/gallery-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) first, then copy:

    <ComponentSource name="gallery-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { GalleryUpload } from "@/components/gallery-upload"
```

```tsx
<GalleryUpload maxFiles={50} onComplete={(items) => saveAlbum(items)} />
```

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  maxFiles: { type: &#x22;number&#x22;, default: &#x22;50&#x22; },
  optimize: {
    type: &#x22;boolean&#x22;,
    default: &#x22;true&#x22;,
    description: &#x22;Downscale to 2560px and convert to WebP.&#x22;,
  },
  onComplete: { type: &#x22;(items) => void&#x22; },
}"
/>


---

# Global Upload (/docs/components/global-upload)



<ComponentPreview name="full-window-dropzone" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/global-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/global-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/global-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/global-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) first, then copy:

    <ComponentSource name="global-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import {
  GlobalDropzone,
  UploadProvider,
  UploadQueuePanel,
} from "@/components/global-upload"
```

```tsx
// app/layout.tsx
<UploadProvider persist>
  {children}
  <GlobalDropzone />
  <UploadQueuePanel />
</UploadProvider>
```

Any component under the provider can add files with `useUploadContext().addFiles(files)`. Uploads keep running during client-side navigation because the provider stays mounted. `GlobalDropzone` ignores drops already handled by an inner dropzone.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  persist: {
    type: &#x22;boolean | UploadPersistence&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Keep uploads in IndexedDB and restore them after reloads.&#x22;,
  },
  guard: {
    type: &#x22;boolean&#x22;,
    default: &#x22;true&#x22;,
    description: &#x22;Warn before leaving the page during uploads.&#x22;,
  },
  &#x22;...options&#x22;: {
    type: &#x22;UploaderOptions&#x22;,
    description: &#x22;Any uploader option (accept, maxSize, concurrency...).&#x22;,
  },
}"
/>

## Examples [#examples]

### Background uploads [#background-uploads]

<ComponentPreview name="background-upload" />


---

# Hourglass (/docs/components/hourglass-upload)



<ComponentPreview name="hourglass-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/hourglass-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/hourglass-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/hourglass-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/hourglass-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="hourglass-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { HourglassUpload } from "@/components/hourglass-upload"
```

```tsx
<HourglassUpload />
```

Both bulbs are clipped rectangles moved by one spring, so the sand in the top and bottom always adds up. The headline shows the estimated time left, updated live. With reduced motion the sand moves without the falling stream.

It uploads through your [adapter](/docs/storage) like every other component, so it works with S3, R2, Cloudinary, local disk or your own API.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    description:
      &#x22;Where files go. Defaults to the UploadConfigProvider adapter.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Identity Verification (/docs/components/identity-verification)



<ComponentPreview name="identity-verification" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/identity-verification
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/identity-verification
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/identity-verification
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/identity-verification
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and the shadcn `button` component, then copy:

    <ComponentSource name="identity-verification" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { IdentityVerification } from "@/components/identity-verification"
```

```tsx
<IdentityVerification onSubmit={(files) => verify(files)} />
```

Built on [`UploadSlot`](/docs/components/upload#slots): one uploader, a named slot per document, each tagged with `meta.slot`. Store identity documents in a private bucket and serve them with short-lived signed URLs.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  steps: { type: &#x22;VerificationStep[]&#x22;, default: &#x22;ID front, ID back, selfie&#x22; },
  optional: {
    type: &#x22;string[]&#x22;,
    default: '[&#x22;id-back&#x22;]',
    description: &#x22;Steps that may be skipped.&#x22;,
  },
  maxSize: { type: &#x22;number&#x22;, default: &#x22;15 MB&#x22; },
  onSubmit: { type: &#x22;(files: Record<string, UploadItem>) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Image Cropper (/docs/components/image-cropper)



<ComponentPreview name="image-crop" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/image-cropper
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/image-cropper
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/image-cropper
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/image-cropper
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) first, then copy:

    <ComponentSource name="image-cropper" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { ImageCropper } from "@/components/ui/image-cropper"
import { useCropQueue } from "@/hooks/use-crop-queue"
```

```tsx
const crops = useCropQueue()

<Upload adapter={adapter} accept="image/*" transform={crops.request}>
  …
</Upload>
<ImageCropper file={crops.current} aspect={1} onCrop={crops.complete} onCancel={crops.skip} />
```

The crop UI is [react-easy-crop](https://github.com/ValentinH/react-easy-crop) (touch, pinch, wheel and keyboard). Rendering uses `transformImage` from `@uploadcn/core/image`: EXIF orientation is applied and metadata is stripped. Install `use-crop-queue` to use it inside the upload pipeline.

## Props [#props]

<TypeTable
  type="{
  file: {
    type: &#x22;File | null&#x22;,
    description: &#x22;The dialog is open while a file is set.&#x22;,
  },
  onCrop: { type: &#x22;(file: File) => void&#x22; },
  onCancel: { type: &#x22;() => void&#x22; },
  aspect: { type: &#x22;number&#x22;, default: &#x22;1&#x22;, description: &#x22;Width / height.&#x22; },
  cropShape: { type: '&#x22;rect&#x22; | &#x22;round&#x22;', default: '&#x22;rect&#x22;' },
  output: {
    type: &#x22;ImageTransformOptions&#x22;,
    description: &#x22;Size, type and quality of the result (default max 2048px).&#x22;,
  },
  title: { type: &#x22;ReactNode&#x22; },
  description: { type: &#x22;ReactNode&#x22; },
}"
/>


---

# Image Metadata (/docs/components/image-metadata)



<ComponentPreview name="image-metadata" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/image-metadata
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/image-metadata
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/image-metadata
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/image-metadata
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and the shadcn `badge`, `input`, `textarea` components, then copy:

    <ComponentSource name="image-metadata" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { ImageMetadataUpload } from "@/components/image-metadata"
```

```tsx
<ImageMetadataUpload
  onSave={(images) =>
    images.map(({ item, alt, caption }) => ({
      key: item.result?.key,
      alt,
      caption,
    }))
  }
/>
```

Alt text and captions are stored on each item's `meta` with `uploader.update(id, { meta })`, so they survive re-renders and travel with the item.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  maxFiles: { type: &#x22;number&#x22;, default: &#x22;8&#x22; },
  requireAlt: {
    type: &#x22;boolean&#x22;,
    default: &#x22;true&#x22;,
    description: &#x22;Require alt text before saving.&#x22;,
  },
  onSave: { type: &#x22;(images: { item, alt, caption }[]) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Image Reveal (/docs/components/image-reveal-upload)



<ComponentPreview name="image-reveal-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/image-reveal-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/image-reveal-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/image-reveal-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/image-reveal-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="image-reveal-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { ImageRevealUpload } from "@/components/image-reveal-upload"
```

```tsx
<ImageRevealUpload onSuccess={(item) => save(item.result)} />
```

The reveal is a `clip-path` driven by the upload percent. The preview is a local object URL, so it appears instantly. With reduced motion the scan line and flash are skipped.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  maxSize: { type: &#x22;number&#x22;, default: &#x22;20 MB&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Image Upload (/docs/components/image-upload)



<ComponentPreview name="image-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/image-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/image-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/image-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/image-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) first, then copy:

    <ComponentSource name="image-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { ImageUpload } from "@/components/image-upload"
```

```tsx
<ImageUpload crop compress maxWidth={2000} />
```

Cropping happens inside the upload pipeline: each image waits in the `validating` state while its crop dialog is open, and several images are cropped one after another. Skipping a crop uploads the original.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  crop: {
    type: &#x22;boolean | { aspect?: number }&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Open a crop dialog for every image.&#x22;,
  },
  compress: {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Resize and re-encode before uploading (WebP by default).&#x22;,
  },
  maxWidth: {
    type: &#x22;number&#x22;,
    default: &#x22;2048&#x22;,
    description: &#x22;Longest edge after compression or cropping.&#x22;,
  },
  maxHeight: { type: &#x22;number&#x22;, default: &#x22;2048&#x22; },
  quality: {
    type: &#x22;number&#x22;,
    default: &#x22;0.82&#x22;,
    description: &#x22;Encoder quality, 0 to 1.&#x22;,
  },
  type: {
    type: '&#x22;image/webp&#x22; | &#x22;image/jpeg&#x22; | &#x22;image/avif&#x22; | &#x22;image/png&#x22;',
    description: &#x22;Output format.&#x22;,
  },
  maxFiles: { type: &#x22;number&#x22;, default: &#x22;12&#x22; },
  maxSize: {
    type: &#x22;number&#x22;,
    default: &#x22;20 MB&#x22;,
    description: &#x22;Max size of the original file.&#x22;,
  },
  minWidth: {
    type: &#x22;number&#x22;,
    description: &#x22;Minimum width of the original image.&#x22;,
  },
  minHeight: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
}"
/>

## Examples [#examples]

### Image crop [#image-crop]

<ComponentPreview name="image-crop" />

### Image compression [#image-compression]

<ComponentPreview name="image-compression" />


---

# Job Application (/docs/components/job-application-upload)



<ComponentPreview name="job-application-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/job-application-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/job-application-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/job-application-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/job-application-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and the shadcn `button`, `input` components, then copy:

    <ComponentSource name="job-application-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { JobApplicationUpload } from "@/components/job-application-upload"
```

```tsx
<JobApplicationUpload
  role="Staff Engineer"
  onSubmit={(application) => apply(application)}
/>
```

Submit stays disabled until the resume has uploaded, so you never receive an application without one.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  role: { type: &#x22;string&#x22; },
  maxSize: { type: &#x22;number&#x22;, default: &#x22;10 MB&#x22; },
  onSubmit: {
    type: &#x22;(application: JobApplication) => void&#x22;,
    description: &#x22;`{ resume, coverLetter?, portfolio?, link? }`&#x22;,
  },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Liquid Dropzone (/docs/components/liquid-dropzone)



<ComponentPreview name="liquid-dropzone" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/liquid-dropzone
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/liquid-dropzone
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/liquid-dropzone
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/liquid-dropzone
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="liquid-dropzone" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { LiquidDropzone } from "@/components/liquid-dropzone"
```

```tsx
<LiquidDropzone maxFiles={20} />
```

Two wave layers loop at different speeds for depth. The level reads from `useUploadProgress`, so it works for any number of files. Waves stop with `prefers-reduced-motion`.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
  showQueue: {
    type: &#x22;boolean&#x22;,
    default: &#x22;true&#x22;,
    description: &#x22;Show the queue under the dropzone.&#x22;,
  },
}"
/>


---

# Logo Upload (/docs/components/logo-upload)



<ComponentPreview name="logo-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/logo-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/logo-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/logo-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/logo-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and the shadcn `card` component, then copy:

    <ComponentSource name="logo-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { LogoUpload } from "@/components/logo-upload"
```

```tsx
<LogoUpload name="Acme Inc" onSuccess={(item) => saveLogo(item.result)} />
```

It's a single-file uploader: choosing a new file replaces the current one.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  name: {
    type: &#x22;string&#x22;,
    default: '&#x22;Acme&#x22;',
    description: &#x22;Initials shown before a logo is uploaded.&#x22;,
  },
  title: { type: &#x22;string&#x22;, default: '&#x22;Logo&#x22;' },
  description: { type: &#x22;string&#x22; },
  maxSize: { type: &#x22;number&#x22;, default: &#x22;2 MB&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Magnetic Dropzone (/docs/components/magnetic-dropzone)



<ComponentPreview name="magnetic-dropzone" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/magnetic-dropzone
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/magnetic-dropzone
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/magnetic-dropzone
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/magnetic-dropzone
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="magnetic-dropzone" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { MagneticDropzone } from "@/components/magnetic-dropzone"
```

```tsx
<MagneticDropzone strength={0.35} />
```

Pointer and `dragover` events feed a spring; it doesn't move at all with `prefers-reduced-motion`.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
  strength: {
    type: &#x22;number&#x22;,
    default: &#x22;0.35&#x22;,
    description: &#x22;How strongly the target follows the pointer, 0–1.&#x22;,
  },
  showQueue: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22; },
}"
/>


---

# OCR Upload (/docs/components/ocr-upload)



<ComponentPreview name="ocr-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/ocr-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/ocr-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/ocr-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/ocr-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    For a server engine, add the route too:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/ocr-route
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/ocr-route
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/ocr-route
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/ocr-route
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and the shadcn `button` component, then copy:

    <ComponentSource name="ocr-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { ocrEndpoint } from "@uploadcn/core"

import { OcrUpload } from "@/components/ocr-upload"
```

```tsx
<OcrUpload
  recognize={ocrEndpoint("/api/ocr")}
  onResult={(item, result) => saveText(item.result.key, result.text)}
/>
```

Files upload through your [adapter](/docs/storage) as usual; after each one is stored, its
text is read and shown. The engine is up to you:

* `ocrEndpoint("/api/ocr")`: your route, with Google Vision, AWS Textract, Azure Document
  Intelligence, Mistral or your own service. Keys stay on the server.
* `tesseractOcr({ load: () => import("tesseract.js") })`: in the browser, with nothing
  uploaded for OCR. The preview above uses it.

See the [OCR guide](/docs/guides/ocr) for every provider.

## Fields [#fields]

Engines with document models return structured fields: Textract's `expense` model and
Azure's `prebuilt-receipt` and `prebuilt-invoice` give `merchant`, `date`, `total`,
`subtotal`, `tax` and more. The block lists them above the text.

## Accessibility [#accessibility]

Documents are a listbox; the text is a focusable, labelled region you can scroll with the
keyboard. Progress and "Reading text…" are announced politely.

## Props [#props]

<TypeTable
  type="{
  recognize: {
    type: &#x22;OcrRecognizer&#x22;,
    description:
      &#x22;Reads the text: `ocrEndpoint(url)`, `tesseractOcr(...)` or your own function.&#x22;,
    required: true,
  },
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    description:
      &#x22;Where files go. Defaults to the UploadConfigProvider adapter.&#x22;,
  },
  required: {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Reject the upload when text can't be read.&#x22;,
  },
  accept: {
    type: &#x22;string&#x22;,
    default: '&#x22;image/png,image/jpeg,image/webp,image/tiff,application/pdf&#x22;',
  },
  maxSize: { type: &#x22;number&#x22;, default: &#x22;20 MB&#x22; },
  maxFiles: { type: &#x22;number&#x22;, default: &#x22;20&#x22; },
  onResult: {
    type: &#x22;(item, result: OcrResult) => void&#x22;,
    description: &#x22;Each file's text, once read.&#x22;,
  },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Orbit (/docs/components/orbit-upload)



<ComponentPreview name="orbit-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/orbit-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/orbit-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/orbit-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/orbit-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="orbit-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { OrbitUpload } from "@/components/orbit-upload"
```

```tsx
<OrbitUpload accept="image/*" />
```

Up to eight files orbit at once; the rest wait in the queue. Orbiting stops with reduced motion.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Paper Plane Button (/docs/components/paper-plane-button)



<ComponentPreview name="paper-plane-button" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/paper-plane-button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/paper-plane-button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/paper-plane-button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/paper-plane-button
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="paper-plane-button" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { PaperPlaneButton } from "@/components/paper-plane-button"
```

```tsx
<PaperPlaneButton>Send to client</PaperPlaneButton>
```

The label is a live region, so screen readers hear Sending, Sent and errors.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
  children: { type: &#x22;ReactNode&#x22;, default: '&#x22;Send files&#x22;' },
}"
/>


---

# Polaroid Upload (/docs/components/polaroid-upload)



<ComponentPreview name="polaroid-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/polaroid-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/polaroid-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/polaroid-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/polaroid-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="polaroid-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { PolaroidUpload } from "@/components/polaroid-upload"
```

```tsx
<PolaroidUpload maxFiles={8} />
```

Each photo gets a stable tilt derived from its id, so re-renders never make it jump.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  maxFiles: { type: &#x22;number&#x22;, default: &#x22;8&#x22; },
  maxSize: { type: &#x22;number&#x22;, default: &#x22;20 MB&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
}"
/>


---

# Product Media (/docs/components/product-media-upload)



<ComponentPreview name="product-media-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/product-media-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/product-media-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/product-media-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/product-media-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and the shadcn `button` component, then copy:

    <ComponentSource name="product-media-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { ProductMediaUpload } from "@/components/product-media-upload"
```

```tsx
<ProductMediaUpload
  maxFiles={8}
  onChange={(images) => setImages(images.map((image) => image.result))}
/>
```

Every tile has keyboard-accessible buttons to make it the cover or move it, so reordering doesn't depend on drag and drop. Order is kept in the component and reported through `onChange`.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  maxFiles: { type: &#x22;number&#x22;, default: &#x22;8&#x22; },
  maxSize: { type: &#x22;number&#x22;, default: &#x22;20 MB&#x22; },
  onChange: {
    type: &#x22;(images) => void&#x22;,
    description: &#x22;Images in display order; the first is the cover.&#x22;,
  },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Progress Ring (/docs/components/progress-ring-upload)



<ComponentPreview name="progress-ring-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/progress-ring-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/progress-ring-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/progress-ring-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/progress-ring-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="progress-ring-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { ProgressRingUpload } from "@/components/progress-ring-upload"
```

```tsx
<ProgressRingUpload />
```

The ring and the number share one `useSpring`, so they never drift apart. The caption under the ring is an `aria-live` region with files, bytes and time left.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Property Photos (/docs/components/property-photos)



<ComponentPreview name="property-photos" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/property-photos
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/property-photos
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/property-photos
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/property-photos
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload), then copy:

    <ComponentSource name="property-photos" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { PropertyPhotos } from "@/components/property-photos"
```

```tsx
<PropertyPhotos
  rooms={[
    "Exterior",
    "Living room",
    "Kitchen",
    "Bedroom",
    "Bathroom",
    "Garden",
  ]}
  recommended={15}
  onChange={(photos) => save(photos)}
/>
```

Room tags live on each item's `meta.room` (set with `uploader.update`), and the room picker is a native `<select>` so it works everywhere, including screen readers.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  rooms: { type: &#x22;string[]&#x22; },
  requiredRooms: { type: &#x22;string[]&#x22;, default: 'all but &#x22;Other&#x22;' },
  recommended: { type: &#x22;number&#x22;, default: &#x22;12&#x22; },
  maxFiles: { type: &#x22;number&#x22;, default: &#x22;40&#x22; },
  onChange: { type: &#x22;(photos: { item, room }[]) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Receipt Upload (/docs/components/receipt-upload)



<ComponentPreview name="receipt-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/receipt-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/receipt-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/receipt-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/receipt-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and the shadcn `button`, `input` components, then copy:

    <ComponentSource name="receipt-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { ReceiptUpload } from "@/components/receipt-upload"
```

With OCR, the form fills itself. Textract's `expense` model and Azure's
`prebuilt-receipt` return the fields directly; other engines are read from the text:

```tsx
import { ocrEndpoint } from "@uploadcn/core"

;<ReceiptUpload
  recognize={ocrEndpoint("/api/ocr")} // npx shadcn@latest add @uploadcn/ocr-route
  onSubmit={(expense) => createExpense(expense)}
/>
```

Or extract the fields yourself, with any API or model:

```tsx
<ReceiptUpload
  extract={async (item) => {
    const response = await fetch(`/api/receipts/${item.result.key}/ocr`)
    return response.json() // { merchant, date, amount, category }
  }}
  onSubmit={(expense) => createExpense(expense)}
/>
```

On phones the picker opens the rear camera (`capture="environment"`). Fields the user already typed are never overwritten. `receiptFromOcr(result)` is exported if you want the same mapping elsewhere. See the [OCR guide](/docs/guides/ocr) for providers.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  categories: { type: &#x22;string[]&#x22; },
  recognize: {
    type: &#x22;OcrRecognizer&#x22;,
    description:
      &#x22;Read the receipt with OCR and prefill merchant, date and amount.&#x22;,
  },
  extract: {
    type: &#x22;(item) => Promise<Partial<ReceiptFields>>&#x22;,
    description:
      &#x22;Prefill from your own OCR or AI after upload. Wins over `recognize`.&#x22;,
  },
  onSubmit: { type: &#x22;(expense) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Ripple Dropzone (/docs/components/ripple-dropzone)



<ComponentPreview name="ripple-dropzone" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/ripple-dropzone
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/ripple-dropzone
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/ripple-dropzone
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/ripple-dropzone
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="ripple-dropzone" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { RippleDropzone } from "@/components/ripple-dropzone"
```

```tsx
<RippleDropzone title="Drop to upload" />
```

It uses the dropzone's `render` prop to read `isDragging` and `isDragReject`; rings turn red for files that don't match `accept`.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  title: { type: &#x22;ReactNode&#x22;, default: '&#x22;Drop to upload&#x22;' },
  description: { type: &#x22;ReactNode&#x22; },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
}"
/>


---

# Rocket (/docs/components/rocket-upload)



<ComponentPreview name="rocket-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/rocket-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/rocket-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/rocket-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/rocket-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="rocket-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { RocketUpload } from "@/components/rocket-upload"
```

```tsx
<RocketUpload accept={[".zip", ".tar.gz"]} />
```

Altitude is a spring driven by the overall percent, so the climb is smooth even when progress arrives in bursts. The status line in the corner is an `aria-live` region with bytes and time left. Smoke and engine flicker are skipped with reduced motion.

It uploads through your [adapter](/docs/storage) like every other component, so it works with S3, R2, Cloudinary, local disk or your own API.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    description:
      &#x22;Where files go. Defaults to the UploadConfigProvider adapter.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Document Scanner (/docs/components/scanner-upload)



<ComponentPreview name="scanner-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/scanner-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/scanner-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/scanner-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/scanner-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="scanner-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { ScannerUpload } from "@/components/scanner-upload"
```

```tsx
<ScannerUpload label="Scan your ID" />
```

On phones the picker opens the rear camera. The frame has an ID-card aspect ratio (1.586:1).

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  label: { type: &#x22;string&#x22;, default: '&#x22;Scan a document&#x22;' },
  accept: { type: &#x22;string&#x22;, default: '&#x22;image/*,application/pdf&#x22;' },
  maxSize: { type: &#x22;number&#x22;, default: &#x22;15 MB&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Shopping Bag (/docs/components/shopping-bag-upload)



<ComponentPreview name="shopping-bag-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/shopping-bag-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/shopping-bag-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/shopping-bag-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/shopping-bag-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="shopping-bag-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { ShoppingBagUpload } from "@/components/shopping-bag-upload"
```

```tsx
<ShoppingBagUpload maxFiles={12} />
```

Pair it with [Product Media](/docs/components/product-media-upload) to order the photos afterwards.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  maxFiles: { type: &#x22;number&#x22;, default: &#x22;12&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Stamp (/docs/components/stamp-upload)



<ComponentPreview name="stamp-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/stamp-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/stamp-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/stamp-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/stamp-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="stamp-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { StampUpload } from "@/components/stamp-upload"
```

```tsx
<StampUpload stamp="Filed" />
```

The four most recent documents stay on the pile with small fixed tilts, so the server and client render the same. Each stamp carries the date in the user's locale. With reduced motion the stamp fades in instead of slamming down.

It uploads through your [adapter](/docs/storage) like every other component, so it works with S3, R2, Cloudinary, local disk or your own API.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    description:
      &#x22;Where files go. Defaults to the UploadConfigProvider adapter.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: {
    type: &#x22;string | string[]&#x22;,
    default: '[&#x22;.pdf&#x22;, &#x22;.doc&#x22;, &#x22;.docx&#x22;, &#x22;image/*&#x22;]',
  },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  stamp: {
    type: &#x22;string&#x22;,
    default: '&#x22;Received&#x22;',
    description: &#x22;Text on the stamp. Failed files are stamped Returned.&#x22;,
  },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Typewriter (/docs/components/typewriter-upload)



<ComponentPreview name="typewriter-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/typewriter-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/typewriter-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/typewriter-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/typewriter-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="typewriter-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { TypewriterUpload } from "@/components/typewriter-upload"
```

```tsx
<TypewriterUpload title="Manuscript" />
```

Names are typed a character at a time, but screen readers get the full name at once from a visually hidden copy. The page grows a line per file, and the keys press while uploads run. With reduced motion, text appears immediately and the keys stay still.

It uploads through your [adapter](/docs/storage) like every other component, so it works with S3, R2, Cloudinary, local disk or your own API.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    description:
      &#x22;Where files go. Defaults to the UploadConfigProvider adapter.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: {
    type: &#x22;string | string[]&#x22;,
    default: '[&#x22;.pdf&#x22;, &#x22;.doc&#x22;, &#x22;.docx&#x22;, &#x22;.txt&#x22;, &#x22;.md&#x22;, &#x22;.rtf&#x22;, &#x22;.odt&#x22;]',
  },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  title: {
    type: &#x22;string&#x22;,
    default: '&#x22;Submission&#x22;',
    description: &#x22;Heading typed at the top of the page.&#x22;,
  },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Upload Button (/docs/components/upload-button)



<ComponentPreview name="upload-button" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/upload-button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/upload-button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/upload-button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/upload-button
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) first, then copy:

    <ComponentSource name="upload-button" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { UploadButton } from "@/components/upload-button"
```

```tsx
<UploadButton
  accept="application/pdf"
  onSuccess={(item) => console.log(item.result)}
>
  Upload invoice
</UploadButton>
```

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  multiple: { type: &#x22;boolean&#x22; },
  showQueue: {
    type: &#x22;boolean&#x22;,
    default: &#x22;true&#x22;,
    description: &#x22;Show the queue under the button.&#x22;,
  },
  children: {
    type: &#x22;ReactNode&#x22;,
    default: '&#x22;Upload file&#x22;',
    description: &#x22;Button label.&#x22;,
  },
  onSuccess: { type: &#x22;(item) => void&#x22; },
}"
/>


---

# Confetti (/docs/components/upload-confetti)



<ComponentPreview name="upload-confetti" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/upload-confetti
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/upload-confetti
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/upload-confetti
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/upload-confetti
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="upload-confetti" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { UploadConfetti } from "@/components/upload-confetti"
```

```tsx
<Upload className="relative">
  <UploadDropzone />
  <UploadQueue />
  <UploadConfetti />
</Upload>
```

It's a part, not a whole uploader: it reads the nearest `<Upload>`. Colors come from `--primary` and `--chart-1…5`, so it matches every theme. Give the parent `relative`.

## Props [#props]

<TypeTable
  type="{
  count: { type: &#x22;number&#x22;, default: &#x22;28&#x22;, description: &#x22;Pieces per burst.&#x22; },
  onlyOnSuccess: {
    type: &#x22;boolean&#x22;,
    default: &#x22;true&#x22;,
    description: &#x22;Skip the burst if any file failed.&#x22;,
  },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Upload Dialog (/docs/components/upload-dialog)



<ComponentPreview name="upload-dialog" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/upload-dialog
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/upload-dialog
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/upload-dialog
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/upload-dialog
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and the shadcn `dialog` component, then copy:

    <ComponentSource name="upload-dialog" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { UploadDialog } from "@/components/upload-dialog"
```

```tsx
<UploadDialog label="Upload files" onDone={(items) => refresh()} />
```

Files are added with `autoUpload: false` so nothing uploads until the user confirms. Closing the dialog mid-upload only hides it, uploads continue and the dialog shows their progress when reopened.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
  title: { type: &#x22;string&#x22;, default: '&#x22;Upload files&#x22;' },
  description: { type: &#x22;string&#x22; },
  label: {
    type: &#x22;ReactNode&#x22;,
    default: '&#x22;Upload files&#x22;',
    description: &#x22;The trigger button's label.&#x22;,
  },
  onDone: {
    type: &#x22;(items) => void&#x22;,
    description: &#x22;Called with the uploaded items when the user clicks Done.&#x22;,
  },
}"
/>


---

# Upload Dock (/docs/components/upload-dock)



<ComponentPreview name="upload-dock" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/upload-dock
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/upload-dock
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/upload-dock
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/upload-dock
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="upload-dock" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { UploadDock } from "@/components/upload-dock"
```

```tsx
<UploadDock accept="image/*" />
```

Magnification follows the cursor with a spring per tile. The `+` tile opens the file picker. Each tile has a screen-reader label with the file name and status.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Upload Field (/docs/components/upload-field)



<ComponentPreview name="form-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/upload-field
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/upload-field
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/upload-field
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/upload-field
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) first, then copy:

    <ComponentSource name="upload-field" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { UploadField } from "@/components/upload-field"
```

```tsx
<Controller
  name="attachments"
  control={form.control}
  render={({ field, fieldState }) => (
    <UploadField
      label="Attachments"
      required
      maxFiles={3}
      error={fieldState.error?.message}
      onChange={field.onChange}
      onBlur={field.onBlur}
      onUploadingChange={setIsUploading}
    />
  )}
/>
```

The value is a list of object keys, not files: uploads happen while the user fills in the form, so submitting is instant.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  label: { type: &#x22;ReactNode&#x22; },
  description: { type: &#x22;ReactNode&#x22; },
  error: {
    type: &#x22;string&#x22;,
    description:
      &#x22;Error message from your form library. Sets `data-invalid` and `aria-invalid`.&#x22;,
  },
  onChange: {
    type: &#x22;(value: string[]) => void&#x22;,
    description: &#x22;Values of successful uploads (object keys by default).&#x22;,
  },
  onBlur: { type: &#x22;() => void&#x22; },
  onUploadingChange: {
    type: &#x22;(uploading: boolean) => void&#x22;,
    description: &#x22;Block submission while files are uploading.&#x22;,
  },
  getValue: {
    type: &#x22;(item) => string&#x22;,
    description: &#x22;Value per successful upload.&#x22;,
  },
  required: { type: &#x22;boolean&#x22; },
  name: {
    type: &#x22;string&#x22;,
    description: &#x22;Also submits hidden inputs in native forms.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
}"
/>

## Examples [#examples]

### Required upload (native form) [#required-upload-native-form]

<ComponentPreview name="required-upload" />

### File restrictions [#file-restrictions]

<ComponentPreview name="file-restrictions" />


---

# Upload Island (/docs/components/upload-island)



<ComponentPreview name="upload-island" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/upload-island
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/upload-island
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/upload-island
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/upload-island
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="upload-island" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { UploadIsland } from "@/components/upload-island"
```

```tsx
<UploadIsland maxFiles={10} />
```

The pill is the dropzone itself, so it's both a button and a drop target. The shape animates with `motion`'s `layout`; content cross-fades with a blur. It expands on hover and on keyboard focus, and its accessible name always describes the progress.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Morphing Button (/docs/components/upload-morph-button)



<ComponentPreview name="upload-morph-button" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/upload-morph-button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/upload-morph-button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/upload-morph-button
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/upload-morph-button
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="upload-morph-button" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { UploadMorphButton } from "@/components/upload-morph-button"
```

```tsx
<UploadMorphButton accept="application/pdf">Upload report</UploadMorphButton>
```

The width animates with `motion`'s `layout`, and the label cross-fades between states. The state is announced through `aria-live`.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  children: {
    type: &#x22;ReactNode&#x22;,
    default: '&#x22;Upload&#x22;',
    description: &#x22;Label in the idle state.&#x22;,
  },
  multiple: { type: &#x22;boolean&#x22; },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  onComplete: { type: &#x22;(items) => void&#x22; },
}"
/>


---

# Odometer (/docs/components/upload-odometer)



<ComponentPreview name="upload-odometer" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/upload-odometer
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/upload-odometer
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/upload-odometer
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/upload-odometer
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="upload-odometer" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { UploadOdometer } from "@/components/upload-odometer"
```

```tsx
<UploadOdometer maxFiles={50} />
```

Digits are decorative (`aria-hidden`); a visually hidden copy of each value is read instead.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Upload Popover (/docs/components/upload-popover)



<ComponentPreview name="upload-popover" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/upload-popover
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/upload-popover
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/upload-popover
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/upload-popover
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and the shadcn `popover` component, then copy:

    <ComponentSource name="upload-popover" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { UploadPopover } from "@/components/upload-popover"
```

```tsx
<UploadPopover label="Attachments" maxSize={10 * 1000 * 1000} />
```

Uploads keep going when the popover closes; the ring on the trigger shows their progress.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
  label: { type: &#x22;string&#x22;, default: '&#x22;Attachments&#x22;' },
}"
/>


---

# Upload Stack (/docs/components/upload-stack)



<ComponentPreview name="upload-stack" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/upload-stack
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/upload-stack
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/upload-stack
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/upload-stack
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="upload-stack" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { UploadStack } from "@/components/upload-stack"
```

```tsx
<UploadStack maxFiles={10} />
```

Collapsed cards beyond the third are `inert`, so keyboard users never land on a hidden card; focusing the stack expands it.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
}"
/>


---

# Upload Table (/docs/components/upload-table)



<ComponentPreview name="upload-table" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/upload-table
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/upload-table
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/upload-table
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/upload-table
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and the shadcn `table` component, then copy:

    <ComponentSource name="upload-table" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { UploadTable } from "@/components/upload-table"
```

```tsx
<UploadTable title="Project files" />
```

Rows are rendered with `UploadItemContext`, so every `UploadItem*` part (status, progress, actions, error) works inside table cells. The drop target is an [`UploadOverlay`](/docs/components/upload#overlay).

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
  title: { type: &#x22;string&#x22;, default: '&#x22;Files&#x22;' },
}"
/>


---

# Upload Tabs (/docs/components/upload-tabs)



<ComponentPreview name="upload-tabs" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/upload-tabs
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/upload-tabs
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/upload-tabs
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/upload-tabs
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and the shadcn `input`, `tabs` components, then copy:

    <ComponentSource name="upload-tabs" />

    <ComponentSource name="use-camera" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { UploadTabs } from "@/components/upload-tabs"
```

```tsx
<UploadTabs sources={["device", "link"]} />
```

Links are fetched in the browser and uploaded like any other file, so the source must allow CORS. The camera starts only when the user clicks **Open camera**.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
  sources: {
    type: '(&#x22;device&#x22; | &#x22;link&#x22; | &#x22;camera&#x22;)[]',
    default: &#x22;all three&#x22;,
    description: &#x22;Which tabs to show.&#x22;,
  },
}"
/>


---

# Upload Terminal (/docs/components/upload-terminal)



<ComponentPreview name="upload-terminal" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/upload-terminal
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/upload-terminal
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/upload-terminal
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/upload-terminal
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="upload-terminal" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { UploadTerminal } from "@/components/upload-terminal"
```

```tsx
<UploadTerminal title="deploy/assets" />
```

The window is always dark, whatever the theme. The log is an `aria-live` list and scrolls to the newest line.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
  title: {
    type: &#x22;string&#x22;,
    default: '&#x22;upload&#x22;',
    description: &#x22;Shown in the title bar.&#x22;,
  },
}"
/>


---

# Upload (/docs/components/upload)



<ComponentPreview name="upload-demo" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install the dependencies:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install @uploadcn/core @uploadcn/react cn class-variance-authority lucide-react
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add @uploadcn/core @uploadcn/react cn class-variance-authority lucide-react
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add @uploadcn/core @uploadcn/react cn class-variance-authority lucide-react
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add @uploadcn/core @uploadcn/react cn class-variance-authority lucide-react
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    Add the shadcn `button` component, then copy this file into your project:

    <ComponentSource name="upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { s3Adapter } from "@uploadcn/core"

import {
  Upload,
  UploadDropzone,
  UploadDropzoneDescription,
  UploadDropzoneHeader,
  UploadDropzoneMedia,
  UploadDropzoneTitle,
  UploadItem,
  UploadItemActions,
  UploadItemContent,
  UploadItemDescription,
  UploadItemMedia,
  UploadItemProgress,
  UploadItemTitle,
  UploadList,
} from "@/components/ui/upload"
```

```tsx
<Upload adapter={s3Adapter({ endpoint: "/api/upload" })} maxFiles={8}>
  <UploadDropzone>
    <UploadDropzoneHeader>
      <UploadDropzoneMedia variant="icon" />
      <UploadDropzoneTitle>Drop files here</UploadDropzoneTitle>
      <UploadDropzoneDescription>or click to browse</UploadDropzoneDescription>
    </UploadDropzoneHeader>
  </UploadDropzone>
  <UploadList>
    <UploadItem>
      <UploadItemMedia />
      <UploadItemContent>
        <UploadItemTitle />
        <UploadItemDescription />
      </UploadItemContent>
      <UploadItemActions />
      <UploadItemProgress />
    </UploadItem>
  </UploadList>
</Upload>
```

## Composition [#composition]

`Upload` holds the uploader. Everything else is a part you place where you want it.

<ComponentTree
  root="{
  name: &#x22;Upload&#x22;,
  description: &#x22;holds the uploader, options or an `uploader` prop&#x22;,
  children: [
    {
      name: &#x22;UploadDropzone&#x22;,
      description: &#x22;drag, drop, click, Enter / Space&#x22;,
      children: [
        {
          name: &#x22;UploadDropzoneHeader&#x22;,
          children: [
            { name: &#x22;UploadDropzoneMedia&#x22; },
            { name: &#x22;UploadDropzoneTitle&#x22; },
            { name: &#x22;UploadDropzoneDescription&#x22; },
          ],
        },
        {
          name: &#x22;UploadDropzoneContent&#x22;,
          description: &#x22;buttons, e.g. UploadTrigger&#x22;,
        },
      ],
    },
    { name: &#x22;UploadTrigger&#x22;, description: &#x22;opens the file picker&#x22; },
    {
      name: &#x22;UploadOverlay&#x22;,
      description: &#x22;turns any content into a drop target&#x22;,
    },
    {
      name: &#x22;UploadSlot&#x22;,
      description: &#x22;a named single-file slot, e.g. “ID front”&#x22;,
    },
    {
      name: &#x22;UploadList&#x22;,
      description: &#x22;renders its children once per file&#x22;,
      children: [
        {
          name: &#x22;UploadItem&#x22;,
          children: [
            {
              name: &#x22;UploadItemMedia&#x22;,
              description: &#x22;thumbnail or file-type icon&#x22;,
            },
            {
              name: &#x22;UploadItemContent&#x22;,
              children: [
                { name: &#x22;UploadItemTitle&#x22;, description: &#x22;file name&#x22; },
                {
                  name: &#x22;UploadItemDescription&#x22;,
                  description: &#x22;size · progress · speed · error&#x22;,
                },
              ],
            },
            {
              name: &#x22;UploadItemActions&#x22;,
              description: &#x22;pause, resume, retry, cancel, remove&#x22;,
            },
            { name: &#x22;UploadItemProgress&#x22; },
          ],
        },
      ],
    },
    {
      name: &#x22;UploadHeader / UploadFooter&#x22;,
      children: [
        {
          name: &#x22;UploadSummary&#x22;,
          description: &#x22;“3 files · 12.4 MB · 45% · 8s left”&#x22;,
        },
      ],
    },
    { name: &#x22;UploadProgress&#x22;, description: &#x22;all files combined&#x22; },
    { name: &#x22;UploadEmpty / UploadStart / UploadClear&#x22; },
  ],
}"
/>

`UploadList` renders its children as a template for every file and provides that file
to the parts inside. There's no render function or prop drilling. Each row re-renders
only when its own file changes.

Parts have sensible defaults and accept children to override them:

```tsx
<UploadItemTitle />                         {/* the file name */}
<UploadItemTitle>Invoice #1042</UploadItemTitle>

<UploadItemActions />                       {/* the applicable actions */}
<UploadItemActions>
  <UploadItemRetry />
  <UploadItemRemove />
</UploadItemActions>
```

## Dropzone [#dropzone]

### Variant [#variant]

Use `variant` to change the surface: `default` (dashed), `muted` or `outline`.

<ComponentPreview name="upload-dropzone-variants" />

### Orientation [#orientation]

`orientation="horizontal"` puts the content side by side, handy for compact forms.
Use `clickable={false}` when the dropzone contains its own `UploadTrigger`.

<ComponentPreview name="upload-dropzone-horizontal" />

### Size [#size]

`size` is `sm`, `default` or `lg`.

```tsx
<UploadDropzone size="sm">…</UploadDropzone>
```

## Item [#item]

### Variant [#variant-1]

`outline` (default), `muted`, `default` (no surface), and `tile` for grids.

<ComponentPreview name="upload-item-variants" />

### Size [#size-1]

`default`, `sm` and `xs`. Media, text and actions scale with the item.

<ComponentPreview name="upload-item-sizes" />

### Tiles [#tiles]

Combine `UploadList variant="grid"` with `UploadItem variant="tile"` and
`UploadItemMedia variant="cover"`.

<ComponentPreview name="upload-grid" />

### Chips [#chips]

`UploadList variant="inline"` with extra-small items makes attachment chips.

<ComponentPreview name="upload-chips" />

## Trigger [#trigger]

`UploadTrigger` renders an outline `Button`. Pass `render` to use any element.

<ComponentPreview name="upload-trigger" />

## Overlay [#overlay]

`UploadOverlay` makes any content a drop target without making it a button. A frosted
layer with a label covers the content only while files are dragged over it, so text
stays selectable and links stay clickable.

<ComponentPreview name="upload-overlay" />

```tsx
<UploadOverlay
  label="Drop to attach"
  description="Files are added to this note"
>
  <Note />
</UploadOverlay>
```

## Slots [#slots]

`UploadSlot` is a named, single-file slot inside a shared `<Upload>`, for forms
that need specific documents. Each slot has its own picker and drop target, replaces
its own file, and tags it with `meta.slot` so your backend knows which is which.
Read a slot's file with `useUploadSlot(name)`.

<ComponentPreview name="upload-slots" />

```tsx
<Upload>
  <UploadSlot
    name="id"
    label="Photo ID"
    accept="image/*,application/pdf"
    required
  />
  <UploadSlot name="address" label="Proof of address" />
</Upload>
```

## Header, footer and summary [#header-footer-and-summary]

`UploadHeader` and `UploadFooter` lay out titles and queue actions. `UploadSummary`
describes the queue in one line and renders nothing while it's empty.

<ComponentPreview name="upload-card" />

## Accessibility [#accessibility]

* `UploadDropzone` is a button: it's focusable and opens the picker with
  <kbd>Enter</kbd> or <kbd>Space</kbd>, the alternative to dragging.
* `UploadItemProgress` is a `progressbar` labelled with the file name.
* A polite live region announces added, finished, failed and rejected files.
* Every action has a name such as “Retry upload of report.pdf”.
* Motion respects `prefers-reduced-motion`.

## API Reference [#api-reference]

### Upload [#upload]

The root. Accepts every [uploader option](/docs/reference/core#uploaderoptions),
`adapter`, `accept`, `maxSize`, `maxFiles`, `concurrency`, `retry`, `transform`,
`process`, `persistence`…, or an `uploader` from [`useUploader`](/docs/hooks#useuploader).

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    description: &#x22;Where files go. Required unless `uploader` is passed.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader you control from outside.&#x22;,
  },
  multiple: {
    type: &#x22;boolean&#x22;,
    default: &#x22;true (false when maxFiles is 1)&#x22;,
    description: &#x22;In single mode a new file replaces the current one.&#x22;,
  },
  disabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  name: {
    type: &#x22;string&#x22;,
    description:
      &#x22;Submit successful uploads as hidden inputs (native forms, server actions).&#x22;,
  },
  messages: {
    type: &#x22;Partial<UploadMessages>&#x22;,
    description: &#x22;Translate every label and announcement.&#x22;,
  },
}"
/>

### UploadDropzone [#uploaddropzone]

<TypeTable
  type="{
  variant: { type: '&#x22;default&#x22; | &#x22;muted&#x22; | &#x22;outline&#x22;', default: '&#x22;default&#x22;' },
  orientation: { type: '&#x22;vertical&#x22; | &#x22;horizontal&#x22;', default: '&#x22;vertical&#x22;' },
  size: { type: '&#x22;sm&#x22; | &#x22;default&#x22; | &#x22;lg&#x22;', default: '&#x22;default&#x22;' },
  clickable: {
    type: &#x22;boolean&#x22;,
    default: &#x22;true&#x22;,
    description: &#x22;Click, Enter and Space open the picker.&#x22;,
  },
}"
/>

Data attributes: `data-dragging`, `data-drag-reject`, `data-disabled`.

### UploadDropzoneMedia [#uploaddropzonemedia]

<TypeTable
  type="{
  variant: {
    type: '&#x22;default&#x22; | &#x22;icon&#x22;',
    default: '&#x22;default&#x22;',
    description:
      &#x22;`icon` draws a bordered circle that lifts on hover and drag.&#x22;,
  },
}"
/>

### UploadList [#uploadlist]

<TypeTable
  type="{
  variant: { type: '&#x22;list&#x22; | &#x22;grid&#x22; | &#x22;inline&#x22;', default: '&#x22;list&#x22;' },
  filter: {
    type: &#x22;(item) => boolean&#x22;,
    description: &#x22;Show only matching files.&#x22;,
  },
  children: {
    type: &#x22;ReactNode | (item) => ReactNode&#x22;,
    description: &#x22;A template rendered per file, or a function of the file.&#x22;,
  },
}"
/>

### UploadItem [#uploaditem]

<TypeTable
  type="{
  variant: {
    type: '&#x22;outline&#x22; | &#x22;muted&#x22; | &#x22;default&#x22; | &#x22;tile&#x22;',
    default: '&#x22;outline&#x22;',
  },
  size: { type: '&#x22;default&#x22; | &#x22;sm&#x22; | &#x22;xs&#x22;', default: '&#x22;default&#x22;' },
  item: {
    type: &#x22;UploadItem&#x22;,
    description: &#x22;Only needed outside UploadList.&#x22;,
  },
}"
/>

Data attributes: `data-status` (`uploading`, `success`, `error`…), `data-variant`, `data-size`.

### UploadItemMedia [#uploaditemmedia]

<TypeTable
  type="{
  variant: {
    type: '&#x22;default&#x22; | &#x22;icon&#x22; | &#x22;cover&#x22;',
    default: '&#x22;default&#x22;',
    description:
      &#x22;`default` shows a thumbnail for images and an icon otherwise.&#x22;,
  },
  thumbnailSize: { type: &#x22;number&#x22;, default: &#x22;128 (400 for cover)&#x22; },
}"
/>

### UploadItemProgress [#uploaditemprogress]

<TypeTable
  type="{
  forceMount: {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Keep the bar after the file finished.&#x22;,
  },
}"
/>

### UploadOverlay [#uploadoverlay]

<TypeTable
  type="{
  label: { type: &#x22;ReactNode&#x22;, default: '&#x22;Drop files to upload&#x22;' },
  description: { type: &#x22;ReactNode&#x22; },
}"
/>

### UploadSlot [#uploadslot]

<TypeTable
  type="{
  name: {
    type: &#x22;string&#x22;,
    description: &#x22;Stored on the file as `meta.slot`.&#x22;,
    required: true,
  },
  label: { type: &#x22;ReactNode&#x22;, required: true },
  description: { type: &#x22;ReactNode&#x22; },
  accept: {
    type: &#x22;string | string[]&#x22;,
    description: &#x22;Checked before the file is added.&#x22;,
  },
  icon: { type: &#x22;ReactNode&#x22; },
  required: {
    type: &#x22;boolean&#x22;,
    description: &#x22;Adds “(required)” to the label.&#x22;,
  },
  children: {
    type: &#x22;ReactNode&#x22;,
    description:
      &#x22;Content for a filled slot. `UploadItem*` parts work inside.&#x22;,
  },
}"
/>

### UploadSummary [#uploadsummary]

Pass children to replace the text. Without children it renders nothing for an empty
queue.

### Actions [#actions]

`UploadItemPause`, `UploadItemResume`, `UploadItemRetry`, `UploadItemCancel` and
`UploadItemRemove` render only when they apply, pause only for resumable adapters.
They accept `Button` props (`variant`, `size`) and `forceMount`.

## Headless [#headless]

The same parts without styles live in `@uploadcn/react`, see the
[custom UI example](/examples#custom-upload-ui).


---

# Video Upload (/docs/components/video-upload)



<ComponentPreview name="video-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/video-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/video-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/video-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/video-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) first, then copy:

    <ComponentSource name="video-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { VideoUpload } from "@/components/video-upload"
```

```tsx
<VideoUpload maxDuration={600} maxSize={2_000_000_000} />
```

With the default `s3Adapter`, files of 64 MB and more switch to multipart: parallel parts, per-part retry, and pause/resume.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    default: 's3Adapter({ endpoint: &#x22;/api/upload&#x22; })',
    description: &#x22;Where files go.&#x22;,
  },
  maxDuration: {
    type: &#x22;number&#x22;,
    description: &#x22;Longest allowed video, in seconds.&#x22;,
  },
  maxSize: { type: &#x22;number&#x22;, default: &#x22;2 GB&#x22; },
  maxFiles: { type: &#x22;number&#x22;, default: &#x22;1&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
}"
/>


---

# Vinyl (/docs/components/vinyl-upload)



<ComponentPreview name="vinyl-upload" />

## Installation [#installation]

<Tabs items="[&#x22;Command&#x22;, &#x22;Manual&#x22;]">
  <Tab value="Command">
    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/vinyl-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/vinyl-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/vinyl-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/vinyl-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Tab>

  <Tab value="Manual">
    Install [Upload](/docs/components/upload) and `motion`, then copy:

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npm install motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn add motion
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add motion
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ComponentSource name="vinyl-upload" />
  </Tab>
</Tabs>

## Usage [#usage]

```tsx
import { VinylUpload } from "@/components/vinyl-upload"
```

```tsx
<VinylUpload maxSize={200 * 1024 * 1024} />
```

The record has momentum: its speed is a spring, so it spins up when uploads start and coasts to a stop instead of freezing. The tonearm angle tracks the overall percent. With reduced motion the record stays still and the arm jumps to its position.

It uploads through your [adapter](/docs/storage) like every other component, so it works with S3, R2, Cloudinary, local disk or your own API.

## Props [#props]

<TypeTable
  type="{
  adapter: {
    type: &#x22;UploadAdapter&#x22;,
    description:
      &#x22;Where files go. Defaults to the UploadConfigProvider adapter.&#x22;,
  },
  uploader: {
    type: &#x22;Uploader&#x22;,
    description: &#x22;An uploader from `useUploader`, instead of options.&#x22;,
  },
  accept: { type: &#x22;string | string[]&#x22;, default: '&#x22;audio/*&#x22;' },
  maxSize: { type: &#x22;number&#x22;, description: &#x22;Bytes.&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  onSuccess: { type: &#x22;(item) => void&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>


---

# Next.js (/docs/frameworks/nextjs)



<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add @uploadcn/file-upload @uploadcn/upload-route
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @uploadcn/file-upload @uploadcn/upload-route
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @uploadcn/file-upload @uploadcn/upload-route
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add @uploadcn/file-upload @uploadcn/upload-route
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Route handler [#route-handler]

`@uploadcn/server` uses Web standard `Request`/`Response`, so the route is one line:

```ts title="app/api/upload/route.ts"
import { createUploadRoute, s3Storage } from "@uploadcn/server"

export const { POST } = createUploadRoute({
  storage: s3Storage({
    bucket: process.env.S3_BUCKET!,
    region: process.env.S3_REGION!,
    accessKeyId: process.env.S3_ACCESS_KEY_ID!,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
  }),
})
```

It runs on the Node.js and Edge runtimes.

## Client components [#client-components]

Upload components use hooks, so they're Client Components. The registry files already
include `"use client"`; render them from Server Components as usual:

```tsx title="app/settings/page.tsx"
import { AvatarUpload } from "@/components/avatar-upload"

export default async function SettingsPage() {
  const user = await getUser()
  return <AvatarUpload src={user.image} />
}
```

## Server actions [#server-actions]

Submit object keys rather than files, see [Forms](/docs/guides/forms#native-forms-and-server-actions).
Next.js limits server action bodies to 1 MB by default, which is another reason to
upload directly to storage.

## App-wide uploads [#app-wide-uploads]

Put `UploadProvider` in `app/layout.tsx` so uploads survive navigation:

```tsx title="app/layout.tsx"
import { GlobalDropzone, UploadProvider, UploadQueuePanel } from "@/components/global-upload"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <UploadProvider persist>
          {children}
          <GlobalDropzone />
          <UploadQueuePanel />
        </UploadProvider>
      </body>
    </html>
  )
}
```


---

# Vite, React Router & others (/docs/frameworks/react)



The client packages have no framework dependencies. In a Vite or React Router app:

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add @uploadcn/file-upload
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @uploadcn/file-upload
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @uploadcn/file-upload
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add @uploadcn/file-upload
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Point the adapter at your backend:

```tsx
import { s3Adapter } from "@uploadcn/core"

import { FileUpload } from "@/components/file-upload"

const adapter = s3Adapter({ endpoint: "https://api.example.com/upload", credentials: "include" })

export function App() {
  return <FileUpload adapter={adapter} />
}
```

## Backends [#backends]

`createUploadRoute` returns a `(request: Request) => Promise<Response>` handler, which
fits any Web-standard server:

<Tabs items="[&#x22;Hono&#x22;, &#x22;Cloudflare Workers&#x22;, &#x22;Bun&#x22;, &#x22;Express&#x22;]">
  <Tab value="Hono">
    ```ts
    import { Hono } from "hono"

    const app = new Hono()
    app.post("/api/upload", (c) => upload.POST(c.req.raw))
    ```
  </Tab>

  <Tab value="Cloudflare Workers">
    ```ts
    export default {
      fetch(request: Request) {
        const url = new URL(request.url)
        if (url.pathname === "/api/upload") return upload.POST(request)
        return new Response("Not found", { status: 404 })
      },
    }
    ```
  </Tab>

  <Tab value="Bun">
    ```ts
    Bun.serve({
      routes: { "/api/upload": { POST: (request) => upload.POST(request) } },
    })
    ```
  </Tab>

  <Tab value="Express">
    ```ts
    import express from "express"

    const app = express()
    app.post("/api/upload", express.json(), async (req, res) => {
      const response = await upload.POST(
        new Request(`http://localhost${req.url}`, {
          method: "POST",
          headers: { "content-type": "application/json", authorization: req.get("authorization") ?? "" },
          body: JSON.stringify(req.body),
        })
      )
      res.status(response.status).json(await response.json())
    })
    ```
  </Tab>
</Tabs>

Not using JavaScript on the server? Implement the [route protocol](/docs/reference/server#protocol)
in any language; it's one JSON endpoint.


---

# TanStack Start (/docs/frameworks/tanstack-start)



<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add @uploadcn/file-upload @uploadcn/upload-route-tanstack
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @uploadcn/file-upload @uploadcn/upload-route-tanstack
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @uploadcn/file-upload @uploadcn/upload-route-tanstack
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add @uploadcn/file-upload @uploadcn/upload-route-tanstack
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Server route [#server-route]

```ts title="src/routes/api/upload.ts"
import { createFileRoute } from "@tanstack/react-router"
import { createUploadRoute, s3Storage } from "@uploadcn/server"

const upload = createUploadRoute({
  storage: s3Storage({
    bucket: process.env.S3_BUCKET!,
    region: process.env.S3_REGION!,
    accessKeyId: process.env.S3_ACCESS_KEY_ID!,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
  }),
})

export const Route = createFileRoute("/api/upload")({
  server: {
    handlers: {
      POST: ({ request }) => upload.POST(request),
    },
  },
})
```

## Components [#components]

Components are identical to Next.js. Nothing in UploadCN depends on a framework:

```tsx title="src/routes/index.tsx"
import { createFileRoute } from "@tanstack/react-router"

import { FileUpload } from "@/components/file-upload"

export const Route = createFileRoute("/")({
  component: () => <FileUpload maxFiles={5} />,
})
```


---

# Getting Started (/docs/getting-started)



## 1. A complete uploader [#1-a-complete-uploader]

The fastest path is a block. It's a regular component in your project:

```tsx
import { FileUpload } from "@/components/file-upload"

<FileUpload accept="image/*,application/pdf" maxSize={20_000_000} maxFiles={10} />
```

Files are validated in the browser, queued (three at a time), uploaded directly to
your bucket through `/api/upload`, retried on network errors, and shown with progress,
speed and time remaining.

## 2. Compose your own [#2-compose-your-own]

Blocks are built from the `upload` primitives. Use them to shape your own layout:

```tsx
import { s3Adapter } from "@uploadcn/core"

import {
  Upload,
  UploadDropzone,
  UploadDropzoneTitle,
  UploadQueue,
} from "@/components/ui/upload"

const adapter = s3Adapter({ endpoint: "/api/upload" })

export function Attachments() {
  return (
    <Upload adapter={adapter} accept={["image/png", "image/jpeg"]} maxSize={10 * 1024 * 1024} maxFiles={5}>
      <UploadDropzone>
        <UploadDropzoneTitle>Drop images here</UploadDropzoneTitle>
      </UploadDropzone>
      <UploadQueue />
    </Upload>
  )
}
```

`UploadQueue` is itself a composition of `UploadList`, `UploadItem`, `UploadPreview`,
`UploadName`, `UploadProgress`, `UploadStatus` and the action buttons, see
[Upload](/docs/components/upload) for every part.

## 3. Control it from outside [#3-control-it-from-outside]

Create the engine with `useUploader` (or `useUpload`, which also returns state) when
other parts of the page need to react to uploads:

```tsx
import { s3Adapter } from "@uploadcn/core"
import { useUpload } from "@uploadcn/react"

const adapter = s3Adapter({ endpoint: "/api/upload" })

export function Composer() {
  const { uploader, summary } = useUpload({
    adapter,
    onSuccess: (item) => console.log("stored at", item.result?.key),
  })

  return (
    <>
      <Upload uploader={uploader}>
        <UploadDropzone />
        <UploadQueue />
      </Upload>
      <Button disabled={summary.isUploading}>Publish</Button>
    </>
  )
}
```

## 4. Pick a storage adapter [#4-pick-a-storage-adapter]

| You have…                         | Use                                                                             |
| --------------------------------- | ------------------------------------------------------------------------------- |
| S3, R2, MinIO, B2, Spaces         | [`s3Adapter`](/docs/adapters/s3) + [`@uploadcn/server`](/docs/reference/server) |
| A signed-URL API (GCS, Supabase…) | [`presignedAdapter`](/docs/adapters/presigned)                                  |
| An endpoint that accepts files    | [`httpAdapter`](/docs/adapters/http)                                            |
| A tus server                      | [`tusAdapter`](/docs/adapters/tus)                                              |
| Your own chunk protocol           | [`multipartAdapter`](/docs/adapters/multipart)                                  |
| No backend yet                    | [`mockAdapter`](/docs/adapters/mock)                                            |

## Next steps [#next-steps]

<Cards>
  <Card title="How it works" href="/docs/how-it-works" />

  <Card title="Validation" href="/docs/guides/validation" />

  <Card title="Resumable uploads" href="/docs/guides/resumable-uploads" />

  <Card title="Examples" href="/examples" />
</Cards>


---

# Accessibility (/docs/guides/accessibility)



Accessibility is built into the primitives, so every block inherits it.

## Keyboard [#keyboard]

* `UploadDropzone` is a focusable button: <kbd>Enter</kbd> or <kbd>Space</kbd> opens
  the file picker. This is the alternative to drag and drop (WCAG 2.5.7 Dragging Movements).
* `UploadTrigger` and every action are native `<button>`s.
* The hidden file input is removed from the tab order so focus never lands on an
  invisible element.
* The image cropper supports arrow keys to move the crop area.

## Screen readers [#screen-readers]

* A polite live region announces files added, uploads finished, failures (with the
  reason) and rejections.
* `UploadProgress` is a `progressbar` with `aria-valuenow`, `aria-valuetext` and a label
  naming the file. Indeterminate states omit `aria-valuenow`.
* Action buttons have explicit names: “Pause upload of video.mp4”.
* Items set `aria-busy` while work is in progress.
* Every string is customizable through `messages` for localization.

## Forms [#forms]

`UploadField` wires `aria-labelledby`, `aria-describedby`, `aria-invalid` and
`aria-required`, and uses shadcn's `Field` for consistent error display.

## Motion [#motion]

Animations are short, subtle, and disabled under `prefers-reduced-motion`
(`motion-reduce:` variants). Status is never conveyed by motion alone.

## Color [#color]

Components use semantic tokens only (`destructive`, `muted-foreground`…), so contrast
follows your theme in light and dark mode. Error states pair color with an icon and text.


---

# Advanced usage (/docs/guides/advanced)



## Headless engine [#headless-engine]

The engine runs anywhere `File` exists, vanilla JS, Svelte, a web worker:

```ts
import { createUploader, s3Adapter } from "@uploadcn/core"

const uploader = createUploader({ adapter: s3Adapter({ endpoint: "/api/upload" }) })
const stop = uploader.mount() // listen for online/offline

uploader.subscribe(() => render(uploader.getState().items))
input.addEventListener("change", () => uploader.add(input.files!))
```

## The render prop [#the-render-prop]

Every primitive can render a different element, like Base UI:

```tsx
<UploadPrimitive.Trigger render={<Button variant="secondary" />}>Browse</UploadPrimitive.Trigger>

<UploadPrimitive.Progress
  render={(props, { percent }) => <CircularProgress {...props} value={percent} />}
/>
```

Event handlers are merged; call `event.preventDefault()` in yours to skip the built-in behavior.

## Concurrency and retries [#concurrency-and-retries]

```ts
createUploader({
  adapter,
  concurrency: 4,
  retry: { retries: 5, baseDelay: 1000, maxDelay: 30_000, factor: 2, jitter: true },
})
```

Delays use exponential backoff with equal jitter, and never undercut a server's
`Retry-After`.

## Transforms [#transforms]

`transform` runs after validation and before queueing. Return a `File` or `Blob`:

```ts
transform: async (file) => (file.type === "image/heic" ? convertHeic(file) : file)
```

`item.originalFile` keeps what the user selected; `item.file` is what gets uploaded.

## Metadata [#metadata]

```ts
await uploader.add(files, { meta: { folder: "invoices" } })
```

`s3Adapter` forwards `meta` to your route (`getKey`, `onUploadComplete`).

## Selective re-rendering [#selective-re-rendering]

Lists re-render only when items are added or removed; each item re-renders only for its
own changes. Use `useUploadSelector` to subscribe to exactly what a component needs.

## Localization [#localization]

```tsx
<Upload messages={{ status: { uploading: "Wird hochgeladen" }, uploaded: (name) => `${name} hochgeladen` }} />
```


---

# AI & LLM uploads (/docs/guides/ai-uploads)



## Chat attachments [#chat-attachments]

<ComponentPreview name="chat-attachment" />

A compact composer for chat interfaces:

* Attach by clicking, dragging onto the composer, or **pasting screenshots**.
* Files upload while the user types; sending waits for them.
* Images are downscaled to 1568px WebP, about what vision models work with, so
  attachments upload faster without changing answers.

Pass the stored objects to your model instead of base64 payloads:

```ts
onSend={async ({ text, attachments }) => {
  await fetch("/api/chat", {
    method: "POST",
    body: JSON.stringify({ text, files: attachments.map((item) => item.result) }),
  })
}}
```

On the server, give the model a signed URL (or fetch the object and pass its bytes) for
each file.

## Document ingestion (RAG) [#document-ingestion-rag]

<ComponentPreview name="ai-document-upload" />

`DocumentIngest` follows each document through `upload → parse → chunk → embed → index`.
The stages are driven by your backend through `process`:

```ts
const ingest: IngestProcess<StoredObject> = async (item, { setStage, signal }) => {
  const { jobId } = await api.ingest(item.result!.key, { signal })
  for await (const event of api.watch(jobId, { signal })) {
    setStage(event.stage) // "parse" | "chunk" | "embed" | "index"
  }
}
```

Throw to fail the item; it can be retried from the list.


---

# Background uploads (/docs/guides/background-uploads)



<ComponentPreview name="background-upload" />

## What's possible [#whats-possible]

| Goal                                     | Reality in browsers                                                                                                         |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Keep uploading while navigating your app | ✓ Keep the uploader in a layout-level provider                                                                              |
| Keep uploading in a background tab       | ✓ Requests continue (timers may be throttled)                                                                               |
| Resume after a reload or crash           | ✓ Persist files + resume state in IndexedDB                                                                                 |
| Coordinate uploads across tabs           | ✓ Web Locks                                                                                                                 |
| Keep uploading after the tab closes      | ✗ Not with JavaScript uploads                                                                                               |
| Background Fetch API                     | Chromium only; requires a service worker and a single request body, so no multipart, signing per part, or progress per part |

UploadCN implements the first four and reports capabilities honestly with
`getBackgroundCapabilities()`.

## App-level uploads [#app-level-uploads]

Put `UploadProvider` in your root layout. Uploads keep running during client-side
navigation, and any component can add files:

```tsx title="app/layout.tsx"
<UploadProvider persist>
  {children}
  <GlobalDropzone />
  <UploadQueuePanel />
</UploadProvider>
```

```tsx
const { addFiles } = useUploadContext()
```

## Persistence [#persistence]

`persist` stores queued files and their resume state in IndexedDB. After a reload or
crash they come back paused and continue from the last finished part. See
[Resumable uploads](/docs/guides/resumable-uploads).

## Leaving the page [#leaving-the-page]

`UploadProvider` warns before closing or reloading the tab while uploads run
(`useUploadGuard`). Browsers show their own message; custom text isn't supported.


---

# Chunked uploads (/docs/guides/chunked-uploads)



<ComponentPreview name="chunked-upload" />

Chunking solves three problems with large files:

* **Reliability**: a dropped connection loses one part, not the whole file.
* **Speed**: several parts upload in parallel, which saturates bandwidth better than one stream.
* **Resumability**: finished parts are recorded, so uploads continue after a pause or reload.

## With S3 or R2 [#with-s3-or-r2]

Nothing to write: `s3Adapter` switches to multipart above its threshold.

```ts
s3Adapter({ endpoint: "/api/upload", multipart: { threshold: 32 * MiB, partSize: 8 * MiB, concurrency: 4 } })
```

## With any other backend [#with-any-other-backend]

Use [`multipartAdapter`](/docs/adapters/multipart) and implement `create`, `uploadPart`
and `complete` against your API. The example above talks to the same route as
`s3Adapter`, written out by hand.

## Choosing a part size [#choosing-a-part-size]

* S3 and R2 require parts of at least **5 MiB** (except the last) and at most **10 000** parts.
  `getPartSize` grows the part size automatically for huge files.
* Larger parts mean fewer requests; smaller parts mean less work lost on failure and
  finer-grained progress. 8–16 MiB is a good default.
* `concurrency` of 3–6 is usually optimal; more rarely helps and competes with the page.

## Chunk progress [#chunk-progress]

Items expose `chunks: { completed, total }` alongside byte progress:

```tsx
const item = useUploadItem()
item.chunks && `${item.chunks.completed}/${item.chunks.total} parts`
```


---

# Forms (/docs/guides/forms)



The pattern: **upload while the user fills in the form, submit object keys.** The form
value is a list of strings, so validation is simple and submitting is instant.

## react-hook-form [#react-hook-form]

<ComponentPreview name="form-upload" />

`UploadField` is controlled: `onChange` receives the keys of successful uploads, and
`onUploadingChange` lets you disable submit while files are still uploading.

## TanStack Form [#tanstack-form]

```tsx
<form.Field
  name="attachments"
  validators={{ onChange: ({ value }) => (value.length ? undefined : "Attach a file") }}
>
  {(field) => (
    <UploadField
      label="Attachments"
      error={field.state.meta.errors[0]}
      onChange={field.handleChange}
      onBlur={field.handleBlur}
    />
  )}
</form.Field>
```

## Native forms and server actions [#native-forms-and-server-actions]

Give `Upload` a `name`; each successful upload renders a hidden input.

<ComponentPreview name="required-upload" />

```tsx title="app/posts/new/page.tsx"
async function createPost(formData: FormData) {
  "use server"
  const images = formData.getAll("images") // object keys
  await db.post.create({ data: { images } })
}

<form action={createPost}>
  <Upload adapter={adapter} name="images">…</Upload>
  <button type="submit">Publish</button>
</form>
```

## Accessibility in forms [#accessibility-in-forms]

* Label the dropzone with `aria-labelledby` pointing at the field label.
* Set `aria-invalid` on the dropzone and `data-invalid` on the `Field` when there's an error.
* Connect the description and error with `aria-describedby`.

`UploadField` does all of this for you.


---

# Image uploads (/docs/guides/image-uploads)



<ComponentPreview name="image-crop" />

All processing uses native browser APIs (`createImageBitmap` and canvas) from
`@uploadcn/core/image`, no image library is shipped.

## Compress before upload [#compress-before-upload]

Plug `imageTransform` into any uploader. Non-images, GIFs and SVGs pass through untouched.

```ts
import { imageTransform } from "@uploadcn/core/image"

<Upload adapter={adapter} accept="image/*" transform={imageTransform({ maxWidth: 2000, quality: 0.82, type: "image/webp" })} />
```

`compressImage` returns the original when re-encoding wouldn't make it smaller.

## Crop [#crop]

`ImageUpload crop` and `AvatarUpload` open the [Image Cropper](/docs/components/image-cropper)
inside the upload pipeline. To crop programmatically:

```ts
import { transformImage } from "@uploadcn/core/image"

const output = await transformImage(file, {
  crop: { x: 120, y: 40, width: 800, height: 800 },
  rotate: 90,
  flipHorizontal: false,
  maxWidth: 512,
  type: "image/webp",
  quality: 0.9,
})
```

## EXIF and privacy [#exif-and-privacy]

* Orientation from EXIF is applied before any other operation, so phone photos are never sideways.
* Re-encoding strips metadata, including **GPS location**: which is usually what you want
  for user uploads. Upload the original file if you need to keep it.

## Validation [#validation]

```tsx
<Upload accept="image/*" image={{ minWidth: 400, minHeight: 400, maxWidth: 8000 }} />
```

## Previews [#previews]

`UploadPreview` and `useFilePreview(file, { thumbnailSize })` downscale large images once
for display, so a gallery of 40 photos doesn't decode 40 full-resolution images.

<ComponentPreview name="image-compression" />


---

# OCR (/docs/guides/ocr)



Text recognition works the same way as storage: one shape for results, and a provider
you can swap. Every engine returns an `OcrResult`:

```ts
interface OcrResult {
  text: string // all text, pages separated by blank lines
  pages: { number: number; text: string; lines?: { text: string; confidence?: number }[] }[]
  confidence?: number // 0 to 1
  fields?: Record<string, { value: string; confidence?: number }> // merchant, date, total…
  markdown?: string // Mistral keeps headings and tables
  provider: string
}
```

<ComponentPreview name="ocr-upload" />

## Pick an engine [#pick-an-engine]

| Engine                                                      | Runs    | Good at                                    | Fields             |
| ----------------------------------------------------------- | ------- | ------------------------------------------ | ------------------ |
| [Tesseract](#in-the-browser)                                | Browser | Private documents, no backend, no cost     | -                  |
| [Google Cloud Vision](#google-cloud-vision)                 | Server  | Photos, handwriting, 50+ languages         | -                  |
| [AWS Textract](#aws-textract)                               | Server  | Forms, receipts and invoices on AWS        | Receipts, invoices |
| [Azure Document Intelligence](#azure-document-intelligence) | Server  | Receipts, invoices, IDs, custom models     | Yes                |
| [Mistral OCR](#mistral-ocr)                                 | Server  | Long PDFs, tables, Markdown for LLMs       | -                  |
| [Your own service](#your-own-service)                       | Server  | PaddleOCR, docTR, EasyOCR, internal models | Yours              |

## How it fits [#how-it-fits]

<Flow label="OCR after upload" steps="[&#x22;Uploading&#x22;, { label: &#x22;Reading text&#x22;, highlight: true }, &#x22;Success&#x22;]" />

OCR runs as the uploader's `process` step, after the file is stored. It doesn't care
where the file went, so it works with every adapter, including `localAdapter`.

```tsx
import { ocrEndpoint, ocrProcess } from "@uploadcn/core"

<Upload adapter={adapter} process={ocrProcess(ocrEndpoint("/api/ocr"))} />
// later: item.meta.ocr is the OcrResult
```

The [OCR Upload](/docs/components/ocr-upload) block does this for you and shows the text,
confidence and fields. [Receipt Upload](/docs/components/receipt-upload) takes the same
`recognize` prop and fills in merchant, date and amount.

## On the server [#on-the-server]

API keys must never reach the browser, so server engines sit behind a route. Add it:

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add @uploadcn/ocr-route
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @uploadcn/ocr-route
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @uploadcn/ocr-route
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add @uploadcn/ocr-route
    ```
  </CodeBlockTab>
</CodeBlockTabs>

That creates `app/api/ocr/route.ts`, which picks a provider from your environment
variables. Or write it yourself:

```ts title="app/api/ocr/route.ts"
import { createOcrRoute, googleVisionOcr, OcrRouteError } from "@uploadcn/server/ocr"

export const { POST } = createOcrRoute({
  provider: googleVisionOcr({ apiKey: process.env.GOOGLE_VISION_API_KEY! }),
  maxFileSize: 20 * 1024 * 1024,
  async authorize({ request }) {
    const session = await auth(request)
    if (!session) throw new OcrRouteError("Unauthorized", 401)
    return session
  },
})
```

Then point the component at it:

```tsx
<OcrUpload recognize={ocrEndpoint("/api/ocr")} />
```

The route:

* authorizes before it reads the body,
* accepts PNG, JPEG, WebP, TIFF, GIF, BMP and PDF; SVG is refused (it can carry script),
* enforces `maxFileSize` from `content-length` and again on the actual file,
* hides provider errors (they can contain account details) and logs them instead.

### Read files that are already stored [#read-files-that-are-already-stored]

Pass `storage` and clients can send `{ "key": "…" }` instead of the file. Check that the
caller owns the key in `authorize`:

```ts
createOcrRoute({
  provider,
  storage: s3Storage({ /* … */ }),
  async authorize({ request, key }) {
    const user = await requireUser(request)
    if (key && !key.startsWith(`${user.id}/`)) throw new OcrRouteError("Forbidden", 403)
  },
})
```

## Providers [#providers]

<Tabs items="[&#x22;Google Vision&#x22;, &#x22;Textract&#x22;, &#x22;Azure&#x22;, &#x22;Mistral&#x22;, &#x22;Custom&#x22;]">
  <Tab value="Google Vision">
    ### Google Cloud Vision [#google-cloud-vision]

    ```ts
    import { googleVisionOcr } from "@uploadcn/server/ocr"

    googleVisionOcr({
      apiKey: process.env.GOOGLE_VISION_API_KEY!, // restrict the key to the Vision API
      languageHints: ["en"],
    })
    ```

    Uses `DOCUMENT_TEXT_DETECTION`. Images go to `images:annotate`; PDFs, TIFFs and GIFs to
    `files:annotate` (the first 5 pages). Prefer a service account? Pass
    `accessToken: () => getAccessToken()` instead of `apiKey`. The key is sent in a header,
    never in the URL.
  </Tab>

  <Tab value="Textract">
    ### AWS Textract [#aws-textract]

    ```ts
    import { awsTextractOcr } from "@uploadcn/server/ocr"

    awsTextractOcr({
      region: process.env.TEXTRACT_REGION!,
      accessKeyId: process.env.TEXTRACT_ACCESS_KEY_ID!,
      secretAccessKey: process.env.TEXTRACT_SECRET_ACCESS_KEY!,
      model: "expense", // or "text"
    })
    ```

    Requests are signed with `aws4fetch`, no AWS SDK. `"text"` calls DetectDocumentText;
    `"expense"` calls AnalyzeExpense and also returns `merchant`, `date`, `total`,
    `subtotal`, `tax` and `currency`. The synchronous APIs take JPEG, PNG, TIFF and
    single-page PDFs up to 10 MB. Give the IAM user only `textract:DetectDocumentText` and
    `textract:AnalyzeExpense`.
  </Tab>

  <Tab value="Azure">
    ### Azure AI Document Intelligence [#azure-ai-document-intelligence]

    ```ts
    import { azureDocumentIntelligenceOcr } from "@uploadcn/server/ocr"

    azureDocumentIntelligenceOcr({
      endpoint: process.env.AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT!,
      apiKey: process.env.AZURE_DOCUMENT_INTELLIGENCE_KEY!,
      model: "prebuilt-receipt", // prebuilt-read, prebuilt-invoice, prebuilt-idDocument, or your model id
    })
    ```

    Starts an analysis and polls it, honouring `Retry-After`. Document fields are mapped to the
    same names as Textract (`merchant`, `date`, `total`…), so receipts work with either. The
    poll URL is only followed on your resource's own origin, because the key is sent with it.
  </Tab>

  <Tab value="Mistral">
    ### Mistral OCR [#mistral-ocr]

    ```ts
    import { mistralOcr } from "@uploadcn/server/ocr"

    mistralOcr({ apiKey: process.env.MISTRAL_API_KEY! })
    ```

    Returns `markdown` that keeps headings, lists and tables, plus plain `text`. A good fit
    when the text goes to an LLM next (see [AI uploads](/docs/guides/ai-uploads)).
  </Tab>

  <Tab value="Custom">
    ### Your own service [#your-own-service]

    Run PaddleOCR, docTR, EasyOCR or Tesseract in a container, or call any other API:

    ```ts
    import { httpOcr } from "@uploadcn/server/ocr"

    httpOcr({
      url: process.env.OCR_SERVICE_URL!, // receives multipart/form-data with "file"
      headers: { authorization: `Bearer ${process.env.OCR_SERVICE_TOKEN}` },
      // Optional: map a different response shape
      parse: (body) => ({ text: body.text, pages: [{ number: 1, text: body.text }] }),
    })
    ```

    Or wrap any function:

    ```ts
    import { createOcrProvider } from "@uploadcn/server/ocr"

    const provider = createOcrProvider("my-engine", async ({ data, type }) => {
      const text = await myEngine.read(data, type)
      return { text, pages: [{ number: 1, text }] }
    })
    ```
  </Tab>
</Tabs>

## In the browser [#in-the-browser]

Tesseract runs in a Web Worker. Nothing is uploaded for OCR and there's no key, which suits
private documents and offline apps. Install it, then:

```bash
npm install tesseract.js
```

```tsx
import { tesseractOcr } from "@uploadcn/core"

const recognize = tesseractOcr({
  load: () => import("tesseract.js"), // loaded on first use
  lang: ["eng", "deu"],
})

<OcrUpload recognize={recognize} accept="image/png,image/jpeg,image/webp" />
```

Tesseract reads images, not PDFs, and is slower and less accurate than the cloud engines on
photos. By default it downloads its engine and language data from a CDN; to self-host them,
pass `workerOptions: { workerPath, corePath, langPath }`.

## Without the block [#without-the-block]

`ocrProcess` stores the result on `item.meta.ocr`; render it however you like:

```tsx
const uploader = useUploader({
  adapter,
  process: ocrProcess(ocrEndpoint("/api/ocr"), { required: true }),
})
```

With `required: true`, a file whose text can't be read is rejected; by default it is kept and
`item.meta.ocrError` explains why.


---

# Offline & reconnection (/docs/guides/offline)



The engine listens to the browser's `online` and `offline` events (once mounted, the
React hooks do this for you).

When the browser goes offline:

* No new uploads start; queued items wait.
* Uploads that fail with a network error are **paused** with `pauseReason: "offline"`
  instead of failing, and the attempt doesn't count against the retry budget.
* `UploadStatus` shows “Waiting for network”.

When it comes back online, offline-paused items are re-queued automatically. Resumable
adapters continue from their last part; others restart.

```ts
uploader.on("online", ({ online }) => console.log(online ? "back online" : "offline"))
const online = useNetworkStatus()
```

<Callout title="What “online” means">
  `navigator.onLine` only says a network interface is up, not that your server is
  reachable. That's why every network failure is also retried with exponential backoff,
  online or not.
</Callout>

## Testing it [#testing-it]

In Chrome DevTools, set **Network → Offline** during an upload. With a resumable adapter
(try the [pause/resume example](/examples#pause-resume)), go back online and watch it continue.


---

# Presigned uploads (/docs/guides/presigned-uploads)



With presigned uploads, your server never handles file bytes. It only signs requests,
which keeps it fast, cheap, and free of body-size limits.

<Sequence
  label="Presigned upload sequence"
  actors="[&#x22;Browser&#x22;, &#x22;Your route&#x22;, &#x22;Bucket&#x22;]"
  messages="[
  { from: 0, to: 0, label: &#x22;Select and validate&#x22; },
  { from: 0, to: 1, label: &#x22;presign { name, type, size }&#x22;, note: &#x22;auth · limits · key&#x22; },
  { from: 1, to: 0, label: &#x22;Signed PUT URL&#x22; },
  { from: 0, to: 2, label: &#x22;PUT bytes&#x22;, note: &#x22;with progress, straight to storage&#x22; },
  { from: 0, to: 1, label: &#x22;complete { key }&#x22;, note: &#x22;HEAD to verify · save metadata&#x22; },
  { from: 1, to: 0, label: &#x22;{ key, url, data }&#x22; },
]"
/>

## What the server enforces [#what-the-server-enforces]

Client-side validation is a convenience; the route is the source of truth.

* **Authentication and authorization**: `authorize` runs before every action.
* **Size**: `maxFileSize` is checked before signing, and the signature locks the
  `Content-Length`, so S3 rejects a larger body.
* **Type**: `allowedTypes` is checked before signing, and the signature locks the
  `Content-Type`.
* **Existence**: `complete` verifies the object with `HEAD` before calling
  `onUploadComplete`, so clients can't register files they never uploaded.
* **Keys**: generated on the server (`getKey`), never trusted from the client.

## Single PUT or multipart? [#single-put-or-multipart]

|                | Single PUT      | Multipart                    |
| -------------- | --------------- | ---------------------------- |
| Max size       | 5 GB (S3)       | 5 TB                         |
| Pause / resume | Restarts from 0 | Continues from the last part |
| Parallelism    | One stream      | Several parts at once        |
| Requests       | 3               | 2 + parts × 2                |

`s3Adapter` picks automatically with `multipart.threshold` (64 MB by default).

## Next.js [#nextjs]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add @uploadcn/upload-route
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @uploadcn/upload-route
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @uploadcn/upload-route
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add @uploadcn/upload-route
    ```
  </CodeBlockTab>
</CodeBlockTabs>

See [Amazon S3](/docs/adapters/s3) and [Cloudflare R2](/docs/adapters/r2) for the full
setup, and [TanStack Start](/docs/frameworks/tanstack-start) for other frameworks.


---

# Processing & scanning (/docs/guides/processing-and-scanning)



<ComponentPreview name="scan-states" />

A browser can't scan files for malware, and UploadCN doesn't pretend to. What it gives
you is states your backend controls.

<Callout title="Looking for built-in scanning?">
  `createUploadRoute` can scan every upload with ClamAV, VirusTotal or your own service
  before it completes. See [Virus scanning](/docs/guides/virus-scanning). This page covers
  driving the states yourself, for background jobs and webhooks. For text recognition, see
  [OCR](/docs/guides/ocr).
</Callout>

<Flow label="Server-side states" steps="[&#x22;Uploading&#x22;, &#x22;Processing&#x22;, { label: &#x22;Scanning&#x22;, highlight: true }, &#x22;Success&#x22;]" branches="[{ from: &#x22;Scanning&#x22;, to: &#x22;Rejected&#x22;, note: &#x22;the scanner found a problem&#x22; }]" />

## With `process` [#with-process]

`process` runs after the adapter stored the file. Move between states with `setStatus`;
throw an `UploadError` with code `"rejected"` to reject.

```ts
import { UploadError } from "@uploadcn/core"

<Upload
  adapter={adapter}
  process={async (item, { setStatus, signal, result }) => {
    setStatus("scanning")
    const verdict = await waitForScan(result.key, { signal }) // poll, SSE, or websocket
    if (verdict === "infected") {
      throw new UploadError("Malware detected", { code: "rejected" })
    }
    return { ...result, scanned: true } // becomes item.result
  }}
/>
```

## From outside (webhooks, realtime) [#from-outside-webhooks-realtime]

When results arrive through another channel, drive the item directly:

```ts
uploader.update(id, { status: "scanning" })
uploader.update(id, { status: "success", result })
uploader.update(id, { status: "rejected", error: "Malware detected" })
```

## Server side [#server-side]

For inline scanning, pass `scan` to `createUploadRoute` ([Virus scanning](/docs/guides/virus-scanning)).
For background scanning, kick it off in `onUploadComplete` (enqueue a job, or rely on your
storage provider's scanning integration) and expose the verdict to the client. Until a file is
approved, keep it out of public access, for example, upload to a quarantine prefix and
copy approved files to their final location.


---

# Resumable uploads (/docs/guides/resumable-uploads)



<ComponentPreview name="resumable-upload" />

## Pause and resume [#pause-and-resume]

Pausing aborts the in-flight request. What happens on resume depends on the adapter:

| Adapter                                                     | Resumable | On resume                                    |
| ----------------------------------------------------------- | --------- | -------------------------------------------- |
| `s3Adapter` (multipart)                                     | ✓         | Continues from the last finished part        |
| `multipartAdapter`                                          | ✓         | Continues from the last finished part        |
| `tusAdapter`                                                | ✓         | Asks the server for the offset and continues |
| `s3Adapter` (single PUT), `presignedAdapter`, `httpAdapter` | ✗         | -                                            |

`UploadPause` only appears for resumable uploads (`uploader.canPause(item)`), so users
are never offered a pause that would silently restart. Queued items can always be paused.

## Surviving reloads [#surviving-reloads]

Pass a persistence store. Queued and in-progress uploads, **including the file bytes**,
are written to IndexedDB along with each adapter's resume state.

```tsx
const [persistence] = React.useState(() => createIndexedDBPersistence())
const uploader = useUploader({ adapter, persistence, restore: true })
```

After a reload, `restore` brings them back as `paused` with `pauseReason: "restored"`.
Call `uploader.resume()` (or let users press resume) to continue.

### Good to know [#good-to-know]

* **Storage quotas.** Browsers allow IndexedDB to use a large share of free disk space,
  but may evict it under pressure. Call `requestPersistentStorage()` to ask for durable
  storage.
* **Multiple tabs.** When Web Locks are available, each running upload holds a lock, and
  `restore()` skips uploads another tab is already running.
* **Expiry.** Records older than 7 days are dropped (`maxAge`).
* **Server state.** Incomplete S3 multipart uploads are billed until aborted. Add a
  bucket lifecycle rule to clean up abandoned ones.

## Persistence for other stores [#persistence-for-other-stores]

Implement the three-method interface to persist elsewhere:

```ts
interface UploadPersistence {
  load(): Promise<PersistedUpload[]>
  save(record: PersistedUpload): Promise<void>
  remove(id: string): Promise<void>
}
```


---

# Validation (/docs/guides/validation)



<ComponentPreview name="file-restrictions" />

```tsx
<Upload
  adapter={adapter}
  accept={["image/png", "image/jpeg"]}
  maxSize={10 * 1024 * 1024}
  minSize={1024}
  maxFiles={5}
  image={{ minWidth: 400, minHeight: 400 }}
  media={{ maxDuration: 600 }}
  duplicates="reject"
  validate={[noSpaces, uniqueNameOnServer]}
/>
```

| Rule                 | Option                                                | Issue code                           |
| -------------------- | ----------------------------------------------------- | ------------------------------------ |
| Type                 | `accept`, MIME types, wildcards or extensions         | `file-invalid-type`                  |
| Size                 | `maxSize`, `minSize`                                  | `file-too-large`, `file-too-small`   |
| Count                | `maxFiles`                                            | `too-many-files`                     |
| Minimum count        | `minFiles` + `validateFileCount`                      | `too-few-files`                      |
| Image dimensions     | `image: { minWidth, minHeight, maxWidth, maxHeight }` | `image-too-small`, `image-too-large` |
| Audio/video duration | `media: { minDuration, maxDuration }`                 | `media-too-short`, `media-too-long`  |
| Duplicates           | `duplicates: "reject" \| "replace" \| "allow"`        | `duplicate`                          |
| Custom               | `validate`                                            | `custom` (or your own)               |

Rejected files appear in the list as `rejected`, with `item.issues` describing why.
`UploadError` renders the messages and the live region announces them.

When the OS doesn't report a MIME type (common for `.md`, `.csv` and others), the
type is inferred from the extension.

## Custom and async validators [#custom-and-async-validators]

Return a message (or `{ code, message }`) to reject; return nothing to accept. Validators
can be async and receive an `AbortSignal` that fires if the file is removed.

```ts
import type { FileValidator } from "@uploadcn/core"

const noSpaces: FileValidator = (file) =>
  file.name.includes(" ") ? "File names can't contain spaces" : null

const uniqueNameOnServer: FileValidator = async (file, { signal }) => {
  const response = await fetch(`/api/files/exists?name=${encodeURIComponent(file.name)}`, { signal })
  const { exists } = await response.json()
  return exists ? "A file with this name already exists" : null
}
```

Cheap checks run first; image, media and custom validators only run if they pass.

## Minimum files [#minimum-files]

`minFiles` is a form-level rule. Check it on submit:

```ts
const issue = validateFileCount(uploadedKeys.length, { minFiles: 1, maxFiles: 3 })
```

## Without uploading [#without-uploading]

```ts
const { validate } = useFileValidation({ accept: ".pdf", maxSize: 5e6 })
const { accepted, rejected } = await validate(files)
```

<Callout type="warn">
  Client-side validation is for user experience. Always enforce limits on the server,
  `createUploadRoute` checks size and type and locks them into the signature.
</Callout>


---

# Virus scanning (/docs/guides/virus-scanning)



A browser can't scan files for malware, so UploadCN never pretends to. Scanning happens in
your upload route, after the file is stored and before the upload completes. The UI only
reflects the verdict.

<Flow label="With scan enabled" steps="[&#x22;Uploading&#x22;, { label: &#x22;Scanning&#x22;, highlight: true }, &#x22;Success&#x22;]" branches="[{ from: &#x22;Scanning&#x22;, to: &#x22;Rejected&#x22;, note: &#x22;malware found: the file is deleted&#x22; }]" />

## Add it to your route [#add-it-to-your-route]

<Steps>
  <Step>
    ### Pick a scanner [#pick-a-scanner]

    ```ts
    import { clamavScanner } from "@uploadcn/server/scan"

    const scanner = clamavScanner({ host: process.env.CLAMAV_HOST })
    ```
  </Step>

  <Step>
    ### Pass it to `createUploadRoute` [#pass-it-to-createuploadroute]

    ```ts title="app/api/upload/route.ts"
    export const { POST } = createUploadRoute({
      storage,
      scan: { scanner },
    })
    ```
  </Step>

  <Step>
    ### That's it on the client [#thats-it-on-the-client]

    Nothing changes in the browser. A clean file completes as usual; an infected one is deleted
    and its item becomes **rejected** with "This file contains malware and was removed". Rejected
    uploads are final: the engine doesn't retry them.
  </Step>
</Steps>

The [upload route](/docs/adapters/s3) from `npx shadcn@latest add @uploadcn/upload-route`
already does this when `CLAMAV_HOST` or `VIRUSTOTAL_API_KEY` is set.

## Scanners [#scanners]

<Tabs items="[&#x22;ClamAV&#x22;, &#x22;VirusTotal&#x22;, &#x22;HTTP service&#x22;, &#x22;Custom&#x22;]">
  <Tab value="ClamAV">
    Free, open source and self-hosted. Files stream to `clamd` over its INSTREAM protocol and
    are never written to disk on your app server.

    ```bash
    docker run -d -p 3310:3310 clamav/clamav:stable
    ```

    ```ts
    import { clamavScanner } from "@uploadcn/server/scan"

    const scanner = clamavScanner({
      host: process.env.CLAMAV_HOST, // or socketPath: "/run/clamav/clamd.sock"
      port: 3310,
      timeout: 60_000,
    })

    await scanner.ping() // true when clamd answers, for health checks
    ```

    clamd refuses streams over its `StreamMaxLength` (25 MB by default). Raise it in
    `clamd.conf` to match your largest upload. ClamAV opens a TCP socket, so the route must run
    on Node.js, not an edge runtime.
  </Tab>

  <Tab value="VirusTotal">
    Checks the file against 70+ engines. By default only the **SHA-256 hash** is sent, so file
    contents stay on your server and only files VirusTotal already knows can be flagged.

    ```ts
    import { virusTotalScanner } from "@uploadcn/server/scan"

    const scanner = virusTotalScanner({
      apiKey: process.env.VIRUSTOTAL_API_KEY!,
      threshold: 2, // engines that must agree before a file counts as infected
    })

    createUploadRoute({ storage, scan: { scanner, onUnknown: "allow" } })
    ```

    Unknown hashes are `unknown`, so pair hash lookups with `onUnknown: "allow"`.

    <Callout type="warn" title="upload: true shares your files">
      With `upload: true`, files VirusTotal hasn't seen are uploaded for analysis. Uploaded files
      are shared with VirusTotal's security partners. Never enable it for private documents.
    </Callout>
  </Tab>

  <Tab value="HTTP service">
    Send files to your own scanning service, or a hosted one such as Cloudmersive,
    MetaDefender or an internal sandbox. The request body is the raw file, described by the
    `content-type` and `x-file-name` headers.

    ```ts
    import { httpScanner } from "@uploadcn/server/scan"

    const scanner = httpScanner({
      url: process.env.SCANNER_URL!,
      headers: { authorization: `Bearer ${process.env.SCANNER_TOKEN}` },
      // Default: { "status": "clean" | "infected", "threats": [] } or { "clean": true }
      parse: (body) => ({
        status: body.CleanResult ? "clean" : "infected",
        threats: body.FoundViruses?.map((virus) => virus.VirusName) ?? [],
      }),
    })
    ```
  </Tab>

  <Tab value="Custom">
    Wrap anything, for example a commercial SDK:

    ```ts
    import { createScanner, readStream } from "@uploadcn/server/scan"

    const scanner = createScanner("my-av", async ({ stream, file }) => {
      const bytes = await readStream(stream, 100 * 1024 * 1024)
      const verdict = await myAntivirus.scan(bytes, file.name)
      return { status: verdict.infected ? "infected" : "clean", threats: verdict.names }
    })
    ```
  </Tab>
</Tabs>

## Options [#options]

<TypeTable
  type="{
  scanner: { type: &#x22;Scanner&#x22;, description: &#x22;Any of the scanners above.&#x22; },
  onUnknown: {
    type: '&#x22;reject&#x22; | &#x22;allow&#x22;',
    default: '&#x22;reject&#x22;',
    description: &#x22;When the scanner can't decide or is down. Reject fails closed and deletes the file.&#x22;,
  },
  maxFileSize: { type: &#x22;number&#x22;, description: &#x22;Files larger than this (bytes) aren't scanned and count as unknown.&#x22; },
  onResult: { type: &#x22;(context) => void&#x22;, description: &#x22;Every verdict with the key, file and auth, for logs, alerts and audit trails.&#x22; },
}"
/>

`onUploadComplete` receives the verdict as `scan`, and the client's `item.result.scan` says
`{ status: "clean", scanner: "clamav" }`. Threat names stay on the server.

```ts
createUploadRoute({
  storage,
  scan: {
    scanner,
    onResult: async ({ key, result, auth }) => {
      if (result.status === "infected") await alertSecurityTeam({ key, user: auth, threats: result.threats })
    },
  },
  async onUploadComplete({ key, scan }) {
    await db.files.create({ key, scannedBy: scan?.scanner })
  },
})
```

## Storage requirements [#storage-requirements]

Scanning reads the stored object back, so the storage must implement `getObject`:
`s3Storage`, `r2Storage` and `createFileSystemStorage` do. `createMemoryStorage` keeps no
bytes and can't be scanned.

## Keep unscanned files private [#keep-unscanned-files-private]

With presigned uploads the bytes reach your bucket before the scan. Keep the bucket
private (no `publicUrl`) so nobody can download a file until `complete` returns, or upload
to a quarantine prefix and copy clean files to their final location in `onUploadComplete`.

## Large files and background scans [#large-files-and-background-scans]

Scanning inline holds the `complete` request open. For multi-gigabyte files, scan in the
background instead: skip `scan`, start a job in `onUploadComplete`, and drive the item from
your job's result with `process` or `uploader.update`. See
[Processing & scanning](/docs/guides/processing-and-scanning).

On AWS, [GuardDuty Malware Protection for S3](https://docs.aws.amazon.com/guardduty/latest/ug/gdu-malware-protection-s3.html)
scans new objects and tags them with `GuardDutyMalwareScanStatus`; poll that tag from
`process`, or wrap it in `createScanner`.

## Test it [#test-it]

The [EICAR test file](https://www.eicar.org/download-anti-malware-testfile/) is harmless,
and every scanner reports it as infected. Upload it to check the whole flow end to end.


---

# Hooks (/docs/hooks)



<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @uploadcn/react @uploadcn/core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @uploadcn/react @uploadcn/core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @uploadcn/react @uploadcn/core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @uploadcn/react @uploadcn/core
    ```
  </CodeBlockTab>
</CodeBlockTabs>

| Hook                                          | Use it to…                                               |
| --------------------------------------------- | -------------------------------------------------------- |
| [`useUploader`](#useuploader)                 | Create an upload engine tied to a component              |
| [`useUpload`](#useupload)                     | Create an engine and read its items, summary and actions |
| [`useUploadState`](#useuploadstate)           | Read state from an existing engine                       |
| [`useUploadSelector`](#useuploadselector)     | Subscribe to a slice of state with minimal re-renders    |
| [`useUploadItem`](#useuploaditem)             | Read one item (inside `UploadItem` or by id)             |
| [`useUploadProgress`](#useuploadprogress)     | Aggregate progress, speed, ETA and counts                |
| [`useUploadValue`](#useuploadvalue)           | Turn successful uploads into form values                 |
| [`useDropzone`](#usedropzone)                 | Add drag-and-drop to any element                         |
| [`useWindowDrop`](#usewindowdrop)             | Detect files dragged anywhere over the page              |
| [`usePasteFiles`](#usepastefiles)             | Upload pasted files and screenshots                      |
| [`useFileValidation`](#usefilevalidation)     | Validate files without uploading them                    |
| [`useImageCompression`](#useimagecompression) | Compress images and report savings                       |
| [`useImageCrop`](#useimagecrop)               | UI-agnostic crop, zoom, rotate and flip state            |
| [`useFilePreview`](#usefilepreview)           | Object URLs and thumbnails with automatic cleanup        |
| [`useNetworkStatus`](#usenetworkstatus)       | Online/offline status                                    |
| [`useUploadGuard`](#useuploadguard)           | Warn before leaving the page during uploads              |

## useUploader [#useuploader]

Creates an engine for the component's lifetime. The instance is stable; option
changes (including a new adapter) apply without recreating it. It's safe under
React Strict Mode.

```tsx
const uploader = useUploader({
  adapter: s3Adapter({ endpoint: "/api/upload" }),
  accept: "image/*",
  maxFiles: 10,
  onSuccess: (item) => toast(`${item.name} uploaded`),
  onError: (item, error) => toast.error(error.message),
})
```

Accepts every [uploader option](/docs/reference/core#uploaderoptions), plus `onAdd`,
`onReject`, `onSuccess`, `onError`, `onComplete` and `restore` (load persisted uploads
on mount).

## useUpload [#useupload]

`useUploader` + `useUploadState` in one call.

```tsx
const { items, summary, add, pause, resume, retry, remove, uploader } = useUpload({ adapter })
```

## useUploadState [#useuploadstate]

```tsx
const { items, summary, online, start, cancel } = useUploadState(uploader)
```

## useUploadSelector [#useuploadselector]

Subscribe to exactly what you render. The component re-renders only when the selected
value changes.

```tsx
const failed = useUploadSelector(uploader, (state) =>
  state.items.filter((item) => item.status === "error").length
)
```

Pass `shallowArrayEqual` as the third argument for selectors that return arrays.

## useUploadItem [#useuploaditem]

```tsx
function FileName() {
  const item = useUploadItem() // inside <UploadItem>
  return <span>{item.name}</span>
}

const item = useUploadItem(id) // anywhere inside <Upload>
```

## useUploadProgress [#useuploadprogress]

```tsx
const { percent, loaded, size, speed, eta, counts, isUploading, isComplete, hasErrors } =
  useUploadProgress(uploader)
```

## useUploadValue [#useuploadvalue]

```tsx
const getKey = (item: UploadItem<StoredObject>) => item.result!.key

const keys = useUploadValue(uploader, getKey) // ["a1b2/photo.jpg", …]
```

Define `getValue` outside the component (or memoize it) to keep the array stable.

## useDropzone [#usedropzone]

```tsx
const { isDragging, isDragReject, handlers } = useDropzone({
  onDrop: (files) => uploader.add(files),
  accept: "image/*",
})

return <div {...handlers} data-dragging={isDragging || undefined}>…</div>
```

Folders are expanded recursively. Drags of disallowed types set `isDragReject` before
the drop, using the MIME types browsers expose while dragging.

## useWindowDrop [#usewindowdrop]

```tsx
const { isDragging } = useWindowDrop({ onDrop: (files) => uploader.add(files) })
```

Drops that an inner dropzone already handled are ignored.

## usePasteFiles [#usepastefiles]

```tsx
usePasteFiles({ onPaste: (files) => uploader.add(files), target: composerRef })
```

Text pastes are left alone; only file pastes (e.g. screenshots) are intercepted.

## useFileValidation [#usefilevalidation]

```tsx
const { validate, validateCount, isValidating } = useFileValidation({ accept: ".pdf", maxSize: 5e6 })
const { accepted, rejected } = await validate(files, { existingCount: 2 })
```

## useImageCompression [#useimagecompression]

```tsx
const { compress, isCompressing, stats } = useImageCompression({ maxWidth: 1600, type: "image/webp" })
const smaller = await compress(file) // stats → { before, after, saved }
```

## useImageCrop [#useimagecrop]

UI-agnostic crop state with an `apply(file)` that renders the result. Pair it with
any crop UI.

```tsx
const crop = useImageCrop()

<Cropper
  crop={crop.position}
  zoom={crop.zoom}
  rotation={crop.rotation}
  onCropChange={crop.setPosition}
  onZoomChange={crop.setZoom}
  onCropComplete={(_, pixels) => crop.setArea(pixels)}
/>

const cropped = await crop.apply(file, { maxWidth: 1024, type: "image/webp" })
```

Also exposes `rotateBy(90)`, `flip("horizontal")` and `reset()`.

## useFilePreview [#usefilepreview]

```tsx
const url = useFilePreview(file, { thumbnailSize: 256 })
```

Object URLs are revoked when the file changes or the component unmounts. With
`thumbnailSize`, large images are downscaled once instead of being decoded at full
resolution for every thumbnail.

## useNetworkStatus [#usenetworkstatus]

```tsx
const online = useNetworkStatus()
```

## useUploadGuard [#useuploadguard]

```tsx
useUploadGuard(uploader) // shows the browser's "Leave site?" dialog while uploading
```


---

# How it works (/docs/how-it-works)



## Layers [#layers]

<ArchitectureDiagram />

The **engine** (`createUploader`) owns all state. React bindings subscribe to it with
`useSyncExternalStore`, so list items re-render only when their own item changes.

## Lifecycle [#lifecycle]

<Flow
  label="Upload lifecycle"
  steps="[
  &#x22;Select&#x22;,
  &#x22;Validate&#x22;,
  &#x22;Transform&#x22;,
  { label: &#x22;Queue&#x22;, note: &#x22;concurrency&#x22; },
  { label: &#x22;Upload&#x22;, note: &#x22;progress · retry&#x22;, highlight: true },
  &#x22;Process&#x22;,
  &#x22;Scan&#x22;,
  &#x22;Complete&#x22;,
]"
  branches="[
  { from: &#x22;Upload&#x22;, to: &#x22;Paused&#x22;, note: &#x22;pause, offline, resume continues from the last part&#x22; },
  { from: &#x22;Upload&#x22;, to: &#x22;Queue&#x22;, note: &#x22;automatic retry with backoff on network and 5xx errors&#x22; },
  { from: &#x22;Any step&#x22;, to: &#x22;Cancelled&#x22;, note: &#x22;cancel aborts the request and cleans up multipart state&#x22; },
]"
/>

1. **Select**: picker, drop (folders expanded), paste, or `uploader.add(files)`.
2. **Validate**: type, size, count, duplicates, image dimensions, media duration and
   your own (async) validators. Failing files become `rejected` with readable issues.
3. **Transform**: optional `transform(file)`: crop, compress, convert.
4. **Queue**: `autoUpload` queues immediately; otherwise items wait as `idle` until
   `start()`. At most `concurrency` uploads run at once.
5. **Upload**: the adapter moves the bytes and reports progress. Retryable failures
   are retried with exponential backoff; resumable adapters can pause and resume.
6. **Process / Scan**: optional `process(item)` reflects server-side work.
7. **Complete**: `success`, or `error` / `rejected` with a reason.

## States [#states]

| Status       | Meaning                                                                                     |
| ------------ | ------------------------------------------------------------------------------------------- |
| `validating` | Running validators and transforms                                                           |
| `idle`       | Ready, waiting for `start()`                                                                |
| `queued`     | Waiting for a free slot (or for a retry delay, see `retryAt`)                               |
| `uploading`  | Bytes are moving                                                                            |
| `paused`     | Paused by the user, by a network loss (`pauseReason: "offline"`) or restored after a reload |
| `processing` | Stored; the server is working on it                                                         |
| `scanning`   | Stored; a malware scan is running on the server                                             |
| `success`    | Done                                                                                        |
| `error`      | Failed; can be retried                                                                      |
| `cancelled`  | Cancelled by the user; can be retried                                                       |
| `rejected`   | Refused by validation or by the server; final                                               |

## Errors [#errors]

Every failure is an `UploadError` with a `code` (`network`, `timeout`, `http`,
`offline`, `validation`, `rejected`, …), an optional HTTP `status`, and a `retryable`
flag. Timeouts, `408`, `425`, `429` and `5xx` are retried; other `4xx` are not.
`Retry-After` headers are honored.

## Events [#events]

```ts
uploader.on("success", ({ item }) => {})
uploader.on("error", ({ item, error }) => {})
uploader.on("retry", ({ item, error, delay }) => {})
uploader.on("complete", ({ items }) => {}) // queue drained
```

All events: `add`, `reject`, `start`, `progress`, `pause`, `resume`, `retry`,
`success`, `error`, `cancel`, `remove`, `statuschange`, `complete`, `online`.


---

# Introduction (/docs)



UploadCN is a set of upload primitives, hooks and complete upload experiences for
[shadcn/ui](https://ui.shadcn.com). It solves the part of file uploads that a dropzone
doesn't: queues, concurrency, retries, chunked and resumable transfers, presigned
S3/R2 flows, validation, image processing, server-side processing and scan states,
offline recovery, persistence and accessibility.

<ComponentPreview name="basic-upload" />

## How it's distributed [#how-its-distributed]

UploadCN follows the same split as shadcn's own components:

| Layer                  | What it is                                         | How you get it                                         |
| ---------------------- | -------------------------------------------------- | ------------------------------------------------------ |
| **UI components**      | Styled, composable shadcn components and blocks    | `npx shadcn add @uploadcn/…`, copied into your project |
| **`@uploadcn/react`**  | Hooks and headless, accessible primitives          | npm dependency, installed by the CLI                   |
| **`@uploadcn/core`**   | The framework-agnostic upload engine and adapters  | npm dependency, installed by the CLI                   |
| **`@uploadcn/server`** | A Web-standard upload route for S3, R2 and friends | npm dependency of the route item                       |

You own every class name and every line of markup. The parts that are easy to get
subtly wrong, retry policies, multipart bookkeeping, request signing, live in small,
tested packages you upgrade like any dependency, the same way shadcn's Drawer builds
on `vaul` and its Toast on `sonner`.

## What's in the box [#whats-in-the-box]

<Cards>
  <Card title="Upload primitives" href="/docs/components/upload">
    Dropzone, trigger, list, item, preview, progress, status and actions.
  </Card>

  <Card title="Complete experiences" href="/docs/components/file-upload">
    File, image, avatar, gallery, video, audio, document, form and AI uploaders.
  </Card>

  <Card title="Hooks" href="/docs/hooks">
    `useUpload`, `useDropzone`, `useImageCrop`, `useWindowDrop` and more.
  </Card>

  <Card title="Storage" href="/docs/adapters">
    Presigned S3 and R2, multipart, tus, plain HTTP, or write your own adapter.
  </Card>
</Cards>

## Principles [#principles]

* **Composable.** Use the parts you need; replace the rest. Every primitive supports a `render` prop.
* **Honest.** No fake progress, no client-side "virus scanning", no background uploads the browser can't deliver.
* **Accessible.** Keyboard-operable dropzones, real `progressbar`s and a polite live region announcing results.
* **Storage-agnostic.** The UI doesn't care where bytes go. Adapters are plain objects.
* **Framework-agnostic core.** Next.js, TanStack Start, Vite, React Router, the engine has no React or Next.js dependency.


---

# Installation (/docs/installation)



UploadCN works with any project set up with the shadcn CLI (Next.js, Vite, TanStack
Start, React Router, Astro…), with either Radix or Base UI primitives and Tailwind CSS v4.

<Steps>
  <Step>
    ### Set up shadcn/ui [#set-up-shadcnui]

    Skip this if your project already has a `components.json`.

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest init
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest init
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest init
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest init
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Step>

  <Step>
    ### Register the `@uploadcn` namespace [#register-the-uploadcn-namespace]

    This adds UploadCN to the `registries` in your `components.json`, so you can install
    items by name.

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest registry add @uploadcn=https://uploadcn.dev/r/{style}/{name}.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest registry add @uploadcn=https://uploadcn.dev/r/{style}/{name}.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest registry add @uploadcn=https://uploadcn.dev/r/{style}/{name}.json
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest registry add @uploadcn=https://uploadcn.dev/r/{style}/{name}.json
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <Callout title="What this changes">
      It adds `"@uploadcn": "https://uploadcn.dev/r/{style}/{name}.json"` to the
      `registries` field of `components.json`. The CLI fills in `{style}` from your
      project (`base-nova`, `radix-lyra`, `aria-maia`…), so every component arrives in
      your style. Icons are converted to your `iconLibrary` on install.
    </Callout>
  </Step>

  <Step>
    ### Add a component [#add-a-component]

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/file-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/file-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/file-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/file-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    The CLI copies `components/ui/upload.tsx` and `components/file-upload.tsx` into your
    project and installs `@uploadcn/react` and `@uploadcn/core`.
  </Step>

  <Step>
    ### Choose where files go [#choose-where-files-go]

    Every component uploads through an **adapter**. Pick the one for your storage; you
    can change it later without touching a single component.

    <Tabs items="[&#x22;S3 / R2&#x22;, &#x22;Cloudinary&#x22;, &#x22;Local disk&#x22;, &#x22;Your API&#x22;, &#x22;Browser only&#x22;]">
      <Tab value="S3 / R2">
        Files go straight from the browser to your bucket; a small route signs each upload.

        <CodeBlockTabs defaultValue="npm">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="npm">
              npm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="pnpm">
              pnpm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="yarn">
              yarn
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="bun">
              bun
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="npm">
            ```bash
            npx shadcn@latest add @uploadcn/upload-route
            ```
          </CodeBlockTab>

          <CodeBlockTab value="pnpm">
            ```bash
            pnpm dlx shadcn@latest add @uploadcn/upload-route
            ```
          </CodeBlockTab>

          <CodeBlockTab value="yarn">
            ```bash
            yarn dlx shadcn@latest add @uploadcn/upload-route
            ```
          </CodeBlockTab>

          <CodeBlockTab value="bun">
            ```bash
            bun x shadcn@latest add @uploadcn/upload-route
            ```
          </CodeBlockTab>
        </CodeBlockTabs>

        This creates `app/api/upload/route.ts` (or use `@uploadcn/upload-route-tanstack`).
        Fill in your credentials, and allow `PUT` from your origin in the bucket's CORS
        settings, exposing the `ETag` header:

        ```bash title=".env.local"
        S3_BUCKET=my-uploads
        S3_REGION=us-east-1
        S3_ACCESS_KEY_ID=…
        S3_SECRET_ACCESS_KEY=…
        ```

        ```ts
        const adapter = s3Adapter({ endpoint: "/api/upload" })
        ```

        See [Amazon S3](/docs/adapters/s3) and [Cloudflare R2](/docs/adapters/r2).
      </Tab>

      <Tab value="Cloudinary">
        Upload straight to Cloudinary. No route is needed with an unsigned preset.

        ```ts
        const adapter = cloudinaryAdapter({ cloudName: "demo", uploadPreset: "unsigned" })
        ```

        See [Cloudinary](/docs/storage/cloudinary) for signed uploads.
      </Tab>

      <Tab value="Local disk">
        Store files on your own server's disk with `@uploadcn/server/fs`, the same route and
        adapter as S3. See [Local disk](/docs/storage/filesystem).
      </Tab>

      <Tab value="Your API">
        Wrap any upload function, your endpoint, Supabase, Firebase, Vercel Blob:

        ```ts
        const adapter = createAdapter(async ({ file, signal, onProgress }) => {
          return myUpload(file, { signal, onProgress })
        })
        ```

        See [Custom adapters](/docs/storage/custom).
      </Tab>

      <Tab value="Browser only">
        Only want the UI? Keep files in the browser and submit them with your form:

        ```ts
        const adapter = localAdapter()
        ```

        See [Browser only](/docs/storage/browser).
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Configure it once [#configure-it-once]

    Add the config wrapper and put it in your root layout. Every UploadCN component below
    it uses that adapter.

    <CodeBlockTabs defaultValue="npm">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @uploadcn/upload-config
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @uploadcn/upload-config
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @uploadcn/upload-config
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @uploadcn/upload-config
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    ```tsx title="app/layout.tsx"
    import { UploadConfig } from "@/components/upload-config"

    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en">
          <body>
            <UploadConfig>{children}</UploadConfig>
          </body>
        </html>
      )
    }
    ```

    Edit the adapter in `components/upload-config.tsx`. A component's own `adapter` prop
    still wins, so one page can upload somewhere else.
  </Step>

  <Step>
    ### Use it [#use-it]

    ```tsx title="app/page.tsx"
    import { FileUpload } from "@/components/file-upload"

    export default function Page() {
      return <FileUpload accept="image/*" maxSize={10_000_000} maxFiles={5} />
    }
    ```
  </Step>
</Steps>

## Installing without the CLI [#installing-without-the-cli]

Everything is plain source. Install the packages, then copy the component source from
each component page (the **Manual** tab).

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @uploadcn/core @uploadcn/react
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @uploadcn/core @uploadcn/react
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @uploadcn/core @uploadcn/react
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @uploadcn/core @uploadcn/react
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Without the namespace [#without-the-namespace]

You can also install any item by URL:

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add https://uploadcn.dev/r/upload.json
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add https://uploadcn.dev/r/upload.json
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add https://uploadcn.dev/r/upload.json
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add https://uploadcn.dev/r/upload.json
    ```
  </CodeBlockTab>
</CodeBlockTabs>


---

# Packages & dependencies (/docs/packages)



shadcn/ui copies components into your project so you own them. UploadCN does the same
for everything you see, but the upload **engine** ships as an npm package. This page
explains why, and what it costs you.

## What you install [#what-you-install]

| Package            | What it is                                                          | Runtime dependencies | Size (gzip)          |
| ------------------ | ------------------------------------------------------------------- | -------------------- | -------------------- |
| `@uploadcn/core`   | Queue, retries, chunking, resume, validation, adapters              | **None**             | \~19 KB              |
| `@uploadcn/react`  | Hooks and headless primitives                                       | `@uploadcn/core`     | \~11 KB              |
| `@uploadcn/server` | Signing routes, S3/R2, local disk, Cloudinary signing (server only) | `aws4fetch`          | server only          |
| `motion`           | Only for [animated components](/docs/components/folder-upload)      | -                    | shared with your app |
| `cn`               | The class helper every shadcn component now uses                    | -                    | tiny                 |

Everything else, `components/ui/upload.tsx` and every block, is **source in your
repo**. Change any of it.

## Why not copy the engine too? [#why-not-copy-the-engine-too]

We considered shipping the engine as source, like most shadcn components. We didn't,
because upload engines are the kind of code you don't want to own:

<div className="not-prose my-6 grid gap-3 sm:grid-cols-2">
  <div className="rounded-xl border bg-card p-4">
    <p className="font-medium">
      Engine as a package (what we do)
    </p>

    <ul className="mt-2 flex list-disc flex-col gap-1 ps-4 text-sm text-muted-foreground">
      <li>
        Bug fixes in retries, multipart and resume arrive with 

        `npm update`

        .
      </li>

      <li>
        100+ tests run against the exact code you ship.
      </li>

      <li>
        Tree-shaken: adapters you don't import aren't bundled.
      </li>

      <li>
        The UI stays yours, restyle or rewrite any component.
      </li>
    </ul>
  </div>

  <div className="rounded-xl border bg-card p-4">
    <p className="font-medium">
      Engine as copied source
    </p>

    <ul className="mt-2 flex list-disc flex-col gap-1 ps-4 text-sm text-muted-foreground">
      <li>
        \~6,500 lines of engine, protocol and React binding code in your repo.
      </li>

      <li>
        Fixes for edge cases (ETag/CORS, Retry-After, StrictMode) never reach you.
      </li>

      <li>
        Every block would duplicate or depend on it anyway.
      </li>

      <li>
        No real customization gain, behavior is configured through options.
      </li>
    </ul>
  </div>
</div>

This is the same split shadcn/ui uses for its hardest components: `Drawer` builds on
`vaul`, `Sonner` on `sonner`, `Calendar` on `react-day-picker`. The behavior is a
dependency; the look is yours.

## When you want no dependencies at all [#when-you-want-no-dependencies-at-all]

* **Only the UI.** Use [`localAdapter`](/docs/storage/browser): no network, no server
  package, and `submit="file"` hands the files to your form.
* **Your own engine.** The headless primitives accept any `uploader` object with the
  same interface, or skip them and build on `useDropzone` and `useFilePreview` alone.
* **No `motion`.** Every non-animated component is CSS-only. Animated ones are opt-in.

## Versioning [#versioning]

The packages follow semver and are released together. Copied components only depend on
the public API, so updating the packages never overwrites your code. When a component
changes, `npx shadcn@latest add @uploadcn/<name> --diff` shows what's new before you
take it.


---

# @uploadcn/core (/docs/reference/core)



<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @uploadcn/core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @uploadcn/core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @uploadcn/core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @uploadcn/core
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Entry points: `@uploadcn/core` (engine, adapters, validation, utilities),
`@uploadcn/core/image` (image processing), `@uploadcn/core/tus` (tus adapter, needs
`tus-js-client`).

## createUploader [#createuploader]

```ts
function createUploader<TResult>(options: UploaderOptions<TResult>): Uploader<TResult>
```

### UploaderOptions [#uploaderoptions]

<TypeTable
  type="{
  adapter: { type: &#x22;UploadAdapter<TResult>&#x22;, required: true },
  autoUpload: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Queue files as soon as they're added.&#x22; },
  concurrency: { type: &#x22;number&#x22;, default: &#x22;3&#x22;, description: &#x22;Simultaneous uploads.&#x22; },
  retry: { type: &#x22;RetryOptions | false&#x22;, default: &#x22;{ retries: 3, baseDelay: 1000, maxDelay: 30000, factor: 2, jitter: true }&#x22; },
  duplicates: { type: '&#x22;reject&#x22; | &#x22;replace&#x22; | &#x22;allow&#x22;', default: '&#x22;reject&#x22;', description: &#x22;Same name, size, type and modification time.&#x22; },
  accept: { type: &#x22;string | string[]&#x22; },
  maxSize: { type: &#x22;number&#x22; },
  minSize: { type: &#x22;number&#x22; },
  maxFiles: { type: &#x22;number&#x22; },
  minFiles: { type: &#x22;number&#x22;, description: &#x22;Checked with validateFileCount.&#x22; },
  image: { type: &#x22;{ minWidth?, minHeight?, maxWidth?, maxHeight? }&#x22; },
  media: { type: &#x22;{ minDuration?, maxDuration? }&#x22;, description: &#x22;Seconds.&#x22; },
  validate: { type: &#x22;FileValidator | FileValidator[]&#x22; },
  transform: { type: &#x22;(file, { signal }) => File | Blob | Promise<File | Blob>&#x22; },
  process: { type: &#x22;(item, { signal, result, setStatus, setMeta }) => Promise<TResult | void>&#x22;, description: &#x22;Server-side work after upload: processing, scanning, ingestion.&#x22; },
  persistence: { type: &#x22;UploadPersistence&#x22;, description: &#x22;e.g. createIndexedDBPersistence().&#x22; },
  network: { type: &#x22;NetworkMonitor | false&#x22;, description: &#x22;Defaults to navigator.onLine in browsers.&#x22; },
  progressInterval: { type: &#x22;number&#x22;, default: &#x22;100&#x22;, description: &#x22;Minimum ms between progress updates.&#x22; },
}"
/>

### Uploader [#uploader]

| Method                                            | Description                                                   |
| ------------------------------------------------- | ------------------------------------------------------------- |
| `add(files, { meta?, start? })`                   | Validate, transform and enqueue. Resolves with the new items. |
| `start(selector?)`                                | Queue idle items.                                             |
| `pause(selector?)` / `resume(selector?)`          | Pause queued or resumable uploads.                            |
| `cancel(selector?)`                               | Abort and clean up server state.                              |
| `retry(selector?)`                                | Retry failed or cancelled items (resets attempts).            |
| `remove(selector?)` / `clearCompleted()`          | Remove items.                                                 |
| `update(id, { status?, result?, error?, meta? })` | Drive processing/scanning states from outside.                |
| `getState()` / `subscribe(listener)`              | Immutable snapshot + change listener.                         |
| `on(event, handler)`                              | Typed events; returns an unsubscribe function.                |
| `getItem(id)` / `canPause(item)`                  | Helpers.                                                      |
| `restore()`                                       | Load persisted uploads (paused).                              |
| `setOptions(partial)` / `getOptions()`            | Update options at runtime.                                    |
| `mount()`                                         | Attach network listeners; returns a cleanup.                  |
| `destroy()`                                       | Abort everything and release resources.                       |

A `selector` is an id, an array of ids, a predicate, or nothing (all items).

## UploadItem [#uploaditem]

<TypeTable
  type="{
  id: { type: &#x22;string&#x22; },
  batchId: { type: &#x22;string&#x22;, description: &#x22;Shared by files added together.&#x22; },
  file: { type: &#x22;File&#x22;, description: &#x22;After transforms.&#x22; },
  originalFile: { type: &#x22;File&#x22;, description: &#x22;As selected.&#x22; },
  &#x22;name / size / type&#x22;: { type: &#x22;string / number / string&#x22; },
  status: { type: &#x22;UploadStatus&#x22; },
  progress: { type: &#x22;{ loaded, total, percent, speed, eta }&#x22; },
  chunks: { type: &#x22;{ completed, total } | null&#x22; },
  error: { type: &#x22;UploadError | null&#x22; },
  issues: { type: &#x22;ValidationIssue[]&#x22;, description: &#x22;Why a file was rejected.&#x22; },
  attempts: { type: &#x22;number&#x22; },
  retryAt: { type: &#x22;number | null&#x22;, description: &#x22;When the next automatic retry happens.&#x22; },
  pauseReason: { type: '&#x22;user&#x22; | &#x22;offline&#x22; | &#x22;restored&#x22; | null' },
  result: { type: &#x22;TResult | undefined&#x22; },
  meta: { type: &#x22;Record<string, unknown>&#x22; },
  resumeState: { type: &#x22;unknown&#x22;, description: &#x22;Adapter-owned, JSON-serializable.&#x22; },
  restored: { type: &#x22;boolean&#x22; },
  &#x22;createdAt / startedAt / completedAt&#x22;: { type: &#x22;number | null&#x22; },
}"
/>

## UploadError [#uploaderror]

```ts
new UploadError(message, { code, retryable?, status?, retryAfter?, details?, cause? })
```

`code`: `network`, `timeout`, `http`, `aborted`, `offline`, `validation`, `rejected`, `unknown`.
Helpers: `isUploadError`, `toUploadError`, `httpError`, `isRetryableStatus`, `parseRetryAfter`.

## Validation [#validation]

`validateFile`, `validateFiles`, `validateFileSync`, `validateFileCount`, `matchesAccept`,
`parseAccept`, `toAcceptAttribute`, `getFileType`.

## Adapters [#adapters]

`s3Adapter`, `r2Adapter`, `presignedAdapter`, `multipartAdapter`, `httpAdapter`,
`routeAdapter`, `mockAdapter`, and `tusAdapter` from `@uploadcn/core/tus`. The default
transport is `xhrTransport` (XMLHttpRequest, for upload progress).

## Persistence & capabilities [#persistence--capabilities]

`createIndexedDBPersistence({ name?, store?, maxAge? })`, `createMemoryPersistence()`,
`getBackgroundCapabilities()`, `requestPersistentStorage()`.

## OCR [#ocr]

`ocrEndpoint(url, options?)` sends files to your OCR route; `tesseractOcr({ load, lang? })`
reads them in the browser; `ocrProcess(recognize, { required?, filter? })` turns either into
an uploader `process` step that stores the result on `item.meta.ocr`. All return or use
`OcrResult`: `{ text, pages, confidence?, fields?, markdown?, provider }`. See
[OCR](/docs/guides/ocr).

## Image (`@uploadcn/core/image`) [#image-uploadcncoreimage]

`transformImage(file, options)`, `compressImage(file, options)`, `imageTransform(options)`,
`getImageDimensions(file)`, `getRotatedSize`, `getFitScale`, `canTransformImage`.

## Utilities [#utilities]

`formatBytes`, `formatSpeed`, `formatDuration`, `getUploadSummary`, `getPartSize`,
`createChunks`, `withRetry`, `getRetryDelay`, `sleep`, `getDroppedFiles`,
`getClipboardFiles`, `isFileDrag`, `getMediaDuration`, `KiB`, `MiB`, `GiB`.


---

# @uploadcn/react (/docs/reference/react)



<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @uploadcn/react @uploadcn/core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @uploadcn/react @uploadcn/core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @uploadcn/react @uploadcn/core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @uploadcn/react @uploadcn/core
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Requires React 19. Every export is a Client Component or hook (the bundle starts with
`"use client"`).

## Hooks [#hooks]

See [Hooks](/docs/hooks): `useUploader`, `useUpload`, `useUploadState`,
`useUploadSelector`, `useUploadItem`, `useUploadProgress`, `useUploadValue`,
`useDropzone`, `useWindowDrop`, `usePasteFiles`, `useFileValidation`,
`useImageCompression`, `useImageCrop`, `useFilePreview`, `useNetworkStatus`,
`useUploadGuard`, `useUploadContext`.

## Primitives [#primitives]

Unstyled, accessible building blocks. The registry's `upload` component wraps them with
shadcn styles; use them directly for a completely custom design.

```tsx
import { Upload } from "@uploadcn/react"

<Upload.Root adapter={adapter}>
  <Upload.Dropzone />
  <Upload.List>{(item) => <Upload.Item item={item}>…</Upload.Item>}</Upload.List>
</Upload.Root>
```

| Primitive                                                     | Element               | Notes                                                                  |
| ------------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------- |
| `Upload.Root`                                                 | `div`                 | Options or `uploader`; hidden input, form values, live region          |
| `Upload.Dropzone`                                             | `div`                 | `role="button"` unless `clickable={false}`; drag state data attributes |
| `Upload.Trigger`                                              | `button`              | Opens the picker                                                       |
| `Upload.List`                                                 | `ul`                  | Function child renders items with isolated re-renders                  |
| `Upload.Item`                                                 | `li`                  | Provides the item to parts inside                                      |
| `Upload.Preview`                                              | `img`                 | Thumbnails images; `fallback` for other types                          |
| `Upload.Name`, `Upload.Size`, `Upload.Speed`, `Upload.Status` | `span`                |                                                                        |
| `Upload.Error`                                                | `p`                   | Error or validation messages                                           |
| `Upload.Success`                                              | -                     | Renders children on success                                            |
| `Upload.Progress` / `Upload.ProgressIndicator`                | `div`                 | `progressbar`; item or aggregate                                       |
| `Upload.Pause`, `Resume`, `Retry`, `Cancel`, `Remove`         | `button`              | Render only when applicable                                            |
| `Upload.Empty`, `Upload.Start`, `Upload.Clear`                | -, `button`, `button` | Queue-level                                                            |

All element primitives accept a `render` prop (element or `(props, state) => element`)
and merge `className`, `style`, refs and event handlers.

## Messages [#messages]

```ts
import { defaultMessages, getStatusLabel, type UploadMessages } from "@uploadcn/react"
```

Pass `messages` to `Upload.Root` to translate status labels, button names and
announcements.


---

# @uploadcn/server (/docs/reference/server)



<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @uploadcn/server
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @uploadcn/server
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @uploadcn/server
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @uploadcn/server
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Runs on Node.js, Bun, Deno, Cloudflare Workers and edge runtimes. Signing uses
[aws4fetch](https://github.com/mhart/aws4fetch) (Web Crypto, \~2.5 KB), no AWS SDK.

## createUploadRoute [#createuploadroute]

```ts
const { POST } = createUploadRoute(options)
// POST(request: Request): Promise<Response>
```

<TypeTable
  type="{
  storage: { type: &#x22;UploadStorage&#x22;, required: true, description: &#x22;s3Storage, r2Storage, createMemoryStorage or your own.&#x22; },
  authorize: { type: &#x22;({ request, action, key? }) => TAuth | Promise<TAuth>&#x22;, description: &#x22;Throw UploadRouteError to deny. The return value is passed to getKey and onUploadComplete.&#x22; },
  maxFileSize: { type: &#x22;number&#x22;, description: &#x22;Bytes. Checked before signing and locked into single-PUT signatures; verified after multipart.&#x22; },
  allowedTypes: { type: &#x22;string | string[]&#x22;, description: &#x22;accept syntax: MIME types, wildcards, extensions.&#x22; },
  getKey: { type: &#x22;({ file, meta, auth, request }) => string&#x22;, default: &#x22;`${uuid}/${sanitized name}`&#x22; },
  expiresIn: { type: &#x22;number&#x22;, default: &#x22;3600&#x22;, description: &#x22;Signed URL lifetime, in seconds.&#x22; },
  onUploadComplete: { type: &#x22;({ key, url, file, meta, auth, request, scan? }) => unknown&#x22;, description: &#x22;Save metadata, start processing. The return value is sent to the client as result.data.&#x22; },
  verify: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;HEAD the object before completing.&#x22; },
  scan: { type: &#x22;{ scanner, onUnknown?, maxFileSize?, onResult? }&#x22;, description: &#x22;Scan uploads before they complete. Infected files are deleted and returned as rejected. See [Virus scanning](/docs/guides/virus-scanning).&#x22; },
}"
/>

Errors thrown as `UploadRouteError(message, status, code?)` are returned as `{ error }`
(plus `code`) with that status. `code: "rejected"` marks the file itself as refused: the
client shows it as rejected and never retries. Anything else becomes a generic `500` and is logged, internal details
never reach the client.

## Storage [#storage]

### s3Storage [#s3storage]

```ts
s3Storage({
  bucket, region, accessKeyId, secretAccessKey,
  sessionToken?, endpoint?, forcePathStyle?, publicUrl?, readUrlExpiresIn?,
})
```

Without `publicUrl`, `url` in results is a signed GET URL.

### r2Storage [#r2storage]

```ts
r2Storage({ accountId, bucket, accessKeyId, secretAccessKey, publicUrl?, jurisdiction? })
```

### createMemoryStorage [#creatememorystorage]

```ts
const { storage, handler } = createMemoryStorage({ baseUrl: "/api/storage", secret })
```

A development storage implementing the full presigned and multipart flow with
HMAC-signed URLs. Bytes are discarded (only size and ETag are kept). Mount `handler`
at `baseUrl` for `PUT` requests. Not for production.

### Custom storage [#custom-storage]

Implement `UploadStorage` (`presignPut`, `createMultipart`, `presignPart`, `listParts`,
`completeMultipart`, `abortMultipart`, `headObject`, `deleteObject`, `getUrl`) to support
any backend. Add the optional `getObject(key)` (a `ReadableStream`) to enable scanning and
OCR of stored files.

## Virus scanning [#virus-scanning]

```ts
import { clamavScanner, createScanner, httpScanner, virusTotalScanner } from "@uploadcn/server/scan"
```

Each returns a `Scanner` whose `scan({ stream, file, key?, signal? })` resolves to
`{ status: "clean" | "infected" | "unknown", threats, scanner, details? }`. See
[Virus scanning](/docs/guides/virus-scanning).

## OCR [#ocr]

```ts
import {
  awsTextractOcr, azureDocumentIntelligenceOcr, createOcrProvider, createOcrRoute,
  googleVisionOcr, httpOcr, mistralOcr,
} from "@uploadcn/server/ocr"
```

Each provider's `recognize({ data, type, name?, signal? })` resolves to an `OcrResult`.
`createOcrRoute({ provider, authorize?, maxFileSize?, allowedTypes?, storage?, onResult? })`
returns `{ POST }`. See [OCR](/docs/guides/ocr).

## Protocol [#protocol]

One `POST` endpoint with a JSON body, dispatched on `action`. Implement it in any language
to use `s3Adapter` with a non-JavaScript backend.

| Action               | Request                                                         | Response                                          |
| -------------------- | --------------------------------------------------------------- | ------------------------------------------------- |
| `presign`            | `{ file: { name, type, size }, meta? }`                         | `{ key, url, method: "PUT", headers }`            |
| `complete`           | `{ key, file, meta? }`                                          | `{ key, url, etag?, data? }`                      |
| `create-multipart`   | `{ file, meta? }`                                               | `{ key, uploadId }`                               |
| `sign-part`          | `{ key, uploadId, partNumber }`                                 | `{ url }`                                         |
| `list-parts`         | `{ key, uploadId }`                                             | `{ parts: [{ partNumber, etag, size }] \| null }` |
| `complete-multipart` | `{ key, uploadId, parts: [{ partNumber, etag }], file, meta? }` | `{ key, url, etag?, data? }`                      |
| `abort-multipart`    | `{ key, uploadId }`                                             | `{ ok: true }`                                    |

Errors: any non-2xx status with `{ "error": "message" }`. `408`, `429` and `5xx` are
retried by the client.


---

# Registry, MCP & AI (/docs/registry)



UploadCN is a standard [shadcn registry](https://ui.shadcn.com/docs/registry). Everything
that works with other registries, the CLI, search, the MCP server, `--diff`, works here.

## Namespace [#namespace]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest registry add @uploadcn=https://uploadcn.dev/r/{style}/{name}.json
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest registry add @uploadcn=https://uploadcn.dev/r/{style}/{name}.json
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest registry add @uploadcn=https://uploadcn.dev/r/{style}/{name}.json
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest registry add @uploadcn=https://uploadcn.dev/r/{style}/{name}.json
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Then install by name:

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add @uploadcn/file-upload @uploadcn/upload-config
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @uploadcn/file-upload @uploadcn/upload-config
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @uploadcn/file-upload @uploadcn/upload-config
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add @uploadcn/file-upload @uploadcn/upload-config
    ```
  </CodeBlockTab>
</CodeBlockTabs>

| URL                      | What it serves                                          |
| ------------------------ | ------------------------------------------------------- |
| `/r/registry.json`       | The index of every item (used by search and MCP)        |
| `/r/{name}.json`         | An item, compiled for the default style (Nova)          |
| `/r/{style}/{name}.json` | An item for your style, e.g. `/r/base-lyra/upload.json` |

## Browse from the CLI [#browse-from-the-cli]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest search @uploadcn --query image
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest search @uploadcn --query image
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest search @uploadcn --query image
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest search @uploadcn --query image
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest view @uploadcn/product-media-upload
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest view @uploadcn/product-media-upload
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest view @uploadcn/product-media-upload
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest view @uploadcn/product-media-upload
    ```
  </CodeBlockTab>
</CodeBlockTabs>

`view` prints the files an item will add before you install it. After an update,
`npx shadcn@latest add @uploadcn/upload --diff` shows what changed against your copy.

## MCP server [#mcp-server]

The [shadcn MCP server](https://ui.shadcn.com/docs/mcp) reads UploadCN's registry index,
so your assistant can find, explain and install components.

<Steps>
  <Step>
    ### Add the namespace [#add-the-namespace]

    Run the `registry add` command above so `@uploadcn` is in `components.json`.
  </Step>

  <Step>
    ### Install the MCP server [#install-the-mcp-server]

    <Tabs items="[&#x22;Claude Code&#x22;, &#x22;Cursor&#x22;, &#x22;VS Code&#x22;]">
      <Tab value="Claude Code">
        <CodeBlockTabs defaultValue="npm">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="npm">
              npm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="pnpm">
              pnpm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="yarn">
              yarn
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="bun">
              bun
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="npm">
            ```bash
            npx shadcn@latest mcp init --client claude
            ```
          </CodeBlockTab>

          <CodeBlockTab value="pnpm">
            ```bash
            pnpm dlx shadcn@latest mcp init --client claude
            ```
          </CodeBlockTab>

          <CodeBlockTab value="yarn">
            ```bash
            yarn dlx shadcn@latest mcp init --client claude
            ```
          </CodeBlockTab>

          <CodeBlockTab value="bun">
            ```bash
            bun x shadcn@latest mcp init --client claude
            ```
          </CodeBlockTab>
        </CodeBlockTabs>
      </Tab>

      <Tab value="Cursor">
        <CodeBlockTabs defaultValue="npm">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="npm">
              npm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="pnpm">
              pnpm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="yarn">
              yarn
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="bun">
              bun
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="npm">
            ```bash
            npx shadcn@latest mcp init --client cursor
            ```
          </CodeBlockTab>

          <CodeBlockTab value="pnpm">
            ```bash
            pnpm dlx shadcn@latest mcp init --client cursor
            ```
          </CodeBlockTab>

          <CodeBlockTab value="yarn">
            ```bash
            yarn dlx shadcn@latest mcp init --client cursor
            ```
          </CodeBlockTab>

          <CodeBlockTab value="bun">
            ```bash
            bun x shadcn@latest mcp init --client cursor
            ```
          </CodeBlockTab>
        </CodeBlockTabs>
      </Tab>

      <Tab value="VS Code">
        <CodeBlockTabs defaultValue="npm">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="npm">
              npm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="pnpm">
              pnpm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="yarn">
              yarn
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="bun">
              bun
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="npm">
            ```bash
            npx shadcn@latest mcp init --client vscode
            ```
          </CodeBlockTab>

          <CodeBlockTab value="pnpm">
            ```bash
            pnpm dlx shadcn@latest mcp init --client vscode
            ```
          </CodeBlockTab>

          <CodeBlockTab value="yarn">
            ```bash
            yarn dlx shadcn@latest mcp init --client vscode
            ```
          </CodeBlockTab>

          <CodeBlockTab value="bun">
            ```bash
            bun x shadcn@latest mcp init --client vscode
            ```
          </CodeBlockTab>
        </CodeBlockTabs>
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Ask [#ask]

    * “Show me the components in the @uploadcn registry”
    * “Add an image upload with crop from @uploadcn”
    * “Build a KYC page with @uploadcn/identity-verification that uploads to Cloudinary”
  </Step>
</Steps>

## llms.txt [#llmstxt]

Agents that don't use MCP can read [`/llms.txt`](/llms.txt): what UploadCN is, how to set
up the registry, every component with its install command, and the docs index.
[`/llms-full.txt`](/llms-full.txt) has the full documentation in one file, and every docs
page is available as Markdown from the **Copy Markdown** button.

## Quality bar [#quality-bar]

Every item in the registry:

* passes `shadcn registry validate` and the registry-directory rules (flat structure, no
  inline content in `registry.json`);
* declares exactly the npm packages and registry items it imports;
* is compiled for all 8 styles with no style classes left over;
* passes `@shadcn/lint` theme checks;
* renders, uploads and passes an accessibility scan in automated tests;
* installs and type-checks in fresh Radix, Base UI and React Aria projects.

## shadcn registry directory [#shadcn-registry-directory]

To list UploadCN in the [registry directory](https://ui.shadcn.com/docs/directory), add
this entry to `apps/v4/registry/directory.json` in
[shadcn-ui/ui](https://github.com/shadcn-ui/ui), run `pnpm validate:registries`, and open
a pull request:

```json title="apps/v4/registry/directory.json"
{
  "name": "@uploadcn",
  "homepage": "https://uploadcn.dev",
  "url": "https://uploadcn.dev/r/{style}/{name}.json",
  "description": "Production-ready file uploads: dropzones, queues, resumable S3 and R2 uploads, and 58 blocks for every style.",
  "author": "Hanzala",
  "logo": "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><rect width='24' height='24' rx='6.5' fill='var(--foreground)'/><g fill='none' stroke='var(--background)' stroke-width='2.4' stroke-linecap='round' stroke-linejoin='round' transform='translate(-0.75 0)'><path d='M7 9v4a5 5 0 0 0 10 0V6'/><path d='m14 9 3-3 3 3'/></g></svg>"
}
```


---

# Browser only (/docs/storage/browser)



```ts
import { localAdapter } from "@uploadcn/core"
```

Sometimes you don't want an upload pipeline: a form that posts files to a server action,
a desktop app, an offline draft, or a prototype. `localAdapter` "uploads" instantly
without a network, and every component keeps working: previews, validation, cropping,
compression, animations.

<ComponentPreview name="ui-only-form" />

## Submit files with a form [#submit-files-with-a-form]

Set `name` and `submit="file"` on `<Upload>`. The selected files are added to the form
like a regular `<input type="file">`:

```tsx title="app/new-post/page.tsx"
import { localAdapter } from "@uploadcn/core"

import { Upload, UploadDropzone, UploadQueue } from "@/components/ui/upload"

const adapter = localAdapter()

export default function NewPost() {
  async function createPost(formData: FormData) {
    "use server"
    const files = formData.getAll("attachments") as File[]
    // Save them wherever you like.
  }

  return (
    <form action={createPost}>
      <Upload adapter={adapter} name="attachments" submit="file">
        <UploadDropzone />
        <UploadQueue />
      </Upload>
      <button type="submit">Post</button>
    </form>
  )
}
```

<Callout title="Transforms apply">
  If you crop or compress images before upload, the form submits the processed file,
  so the server receives the smaller version.
</Callout>

## Read files in code [#read-files-in-code]

The result of each item carries the `File` and a preview URL:

```tsx
<FileUpload
  adapter={localAdapter()}
  onSuccess={(item) => {
    item.result.file // File
    item.result.url  // blob: URL for previews
  }}
/>
```

## Keep files across reloads [#keep-files-across-reloads]

With `store: "indexeddb"`, files are also saved in the browser. Read them back later,
even after a reload, with `getLocalFile`:

```ts
import { getLocalFile, localAdapter } from "@uploadcn/core"

const adapter = localAdapter({ store: "indexeddb" })

// later
const file = await getLocalFile(item.id)
```

Remove them with `deleteLocalFile(id)` when you're done.


---

# Cloudinary (/docs/storage/cloudinary)



```ts
import { cloudinaryAdapter } from "@uploadcn/core"
```

Files go directly from the browser to Cloudinary's upload API, with real progress. You
don't need the Cloudinary SDK.

## Unsigned uploads [#unsigned-uploads]

Create an **unsigned upload preset** in the Cloudinary console (Settings → Upload) and
restrict it there: allowed formats, max file size, folder, moderation.

```ts
const adapter = cloudinaryAdapter({
  cloudName: process.env.NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME!,
  uploadPreset: "user-uploads",
  folder: "avatars",
})
```

<Callout type="warn" title="Anyone can use an unsigned preset">
  The preset name is public. Use unsigned presets only for low-risk uploads, and lock
  the preset down. For anything tied to a user, sign uploads on your server.
</Callout>

## Signed uploads [#signed-uploads]

Your server decides what's allowed and signs the parameters with your API secret. The
secret never reaches the browser.

<Steps>
  <Step>
    ### Add a signing route [#add-a-signing-route]

    ```ts title="app/api/cloudinary/route.ts"
    import { signCloudinaryParams } from "@uploadcn/server"

    export async function POST(request: Request) {
      const session = await auth()
      if (!session) return new Response("Unauthorized", { status: 401 })

      const params = (await request.json()) as Record<string, string>
      // Only sign what this user may upload.
      if (params.folder !== `users/${session.user.id}`) {
        return new Response("Forbidden", { status: 403 })
      }

      return Response.json(
        await signCloudinaryParams(params, {
          apiKey: process.env.CLOUDINARY_API_KEY!,
          apiSecret: process.env.CLOUDINARY_API_SECRET!,
        })
      )
    }
    ```
  </Step>

  <Step>
    ### Ask it for a signature [#ask-it-for-a-signature]

    ```ts
    const adapter = cloudinaryAdapter({
      cloudName: process.env.NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME!,
      folder: `users/${userId}`,
      sign: (params) =>
        fetch("/api/cloudinary", {
          method: "POST",
          headers: { "content-type": "application/json" },
          body: JSON.stringify(params),
        }).then((response) => response.json()),
    })
    ```
  </Step>
</Steps>

## Large files [#large-files]

Files larger than `chunkSize` (default 20 MB, minimum 5 MB) upload in chunks using
Cloudinary's chunked upload API. Each finished chunk is saved as resume state, so a retry
(or a reload with [persistence](/docs/guides/resumable-uploads)) continues from the last
chunk instead of starting over.

## The result [#the-result]

Each successful item's `result` is Cloudinary's upload response:

```ts
onSuccess={(item) => {
  item.result.secure_url // https://res.cloudinary.com/…
  item.result.public_id
  item.result.width
}}
```

## Options [#options]

<TypeTable
  type="{
  cloudName: { type: &#x22;string&#x22;, required: true },
  uploadPreset: { type: &#x22;string&#x22;, description: &#x22;An unsigned preset. Use this or `sign`.&#x22; },
  sign: { type: &#x22;(params, item) => Promise<{ signature, timestamp, apiKey }>&#x22;, description: &#x22;Signs `{ ...params, timestamp }` on your server.&#x22; },
  resourceType: { type: '&#x22;auto&#x22; | &#x22;image&#x22; | &#x22;video&#x22; | &#x22;raw&#x22;', default: '&#x22;auto&#x22;' },
  folder: { type: &#x22;string&#x22; },
  params: { type: &#x22;Record<string, string> | (item) => Record<string, string>&#x22;, description: &#x22;Extra upload parameters: tags, context, public_id…&#x22; },
  chunkSize: { type: &#x22;number&#x22;, default: &#x22;20 MB&#x22; },
  apiUrl: { type: &#x22;string&#x22;, default: '&#x22;https://api.cloudinary.com/v1_1&#x22;' },
}"
/>


---

# Custom adapters (/docs/storage/custom)



```ts
import { createAdapter } from "@uploadcn/core"
```

An adapter is one async function: it receives the file and returns whatever your backend
returns. Report progress and honour the abort signal, and the engine gives you queueing,
retries, cancel and the whole UI for free.

<ComponentPreview name="custom-adapter" />

```ts
const adapter = createAdapter(async ({ file, signal, onProgress, item }) => {
  // item.meta has anything you attached, e.g. the slot name
  const result = await uploadSomewhere(file, { signal, onProgress })
  return result // becomes item.result
})
```

<TypeTable
  type="{
  file: { type: &#x22;File&#x22;, description: &#x22;The file to upload, after transforms.&#x22; },
  item: { type: &#x22;UploadItem&#x22;, description: &#x22;Id, name, meta, attempt…&#x22; },
  signal: { type: &#x22;AbortSignal&#x22;, description: &#x22;Aborted on cancel, pause and remove.&#x22; },
  onProgress: { type: &#x22;(loaded: number, total?: number) => void&#x22; },
  attempt: { type: &#x22;number&#x22;, description: &#x22;1 on the first try, 2 on the first retry…&#x22; },
  resumeState: { type: &#x22;unknown&#x22;, description: &#x22;What you saved with `saveResumeState`.&#x22; },
  saveResumeState: { type: &#x22;(state: unknown) => void&#x22;, description: &#x22;Save progress so a retry can continue.&#x22; },
}"
/>

Throw an `UploadError` to control retries: `retryable: true` for transient failures,
`false` for permanent ones. Plain errors and HTTP 5xx/429 are retried; 4xx are not.

## Recipes [#recipes]

<Tabs items="[&#x22;Your endpoint&#x22;, &#x22;Vercel Blob&#x22;, &#x22;Firebase&#x22;, &#x22;Supabase&#x22;, &#x22;Server action&#x22;]">
  <Tab value="Your endpoint">
    No wrapper needed: `httpAdapter` posts `multipart/form-data` with progress:

    ```ts
    import { httpAdapter } from "@uploadcn/core"

    const adapter = httpAdapter({
      url: "/api/files",
      headers: async () => ({ authorization: `Bearer ${await getToken()}` }),
    })
    ```
  </Tab>

  <Tab value="Vercel Blob">
    Client uploads go straight to Vercel Blob; your `handleUploadUrl` route authorizes them
    (see the Vercel Blob docs).

    ```ts
    import { upload } from "@vercel/blob/client"
    import { createAdapter } from "@uploadcn/core"

    const adapter = createAdapter(
      ({ file, signal, onProgress }) =>
        upload(file.name, file, {
          access: "public",
          handleUploadUrl: "/api/blob",
          abortSignal: signal,
          onUploadProgress: ({ loaded }) => onProgress(loaded),
        }),
      { name: "vercel-blob" }
    )
    ```
  </Tab>

  <Tab value="Firebase">
    ```ts
    import { createAdapter } from "@uploadcn/core"
    import { getDownloadURL, ref, uploadBytesResumable } from "firebase/storage"

    import { storage } from "@/lib/firebase"

    const adapter = createAdapter(
      ({ file, item, signal, onProgress }) =>
        new Promise((resolve, reject) => {
          const task = uploadBytesResumable(ref(storage, `uploads/${item.id}`), file)
          signal.addEventListener("abort", () => task.cancel())
          task.on(
            "state_changed",
            (snapshot) => onProgress(snapshot.bytesTransferred),
            reject,
            async () => resolve({ url: await getDownloadURL(task.snapshot.ref) })
          )
        }),
      { name: "firebase" }
    )
    ```
  </Tab>

  <Tab value="Supabase">
    Create a signed upload URL on your server, then upload with it. Supabase's client
    doesn't report progress, so the item jumps to 100% when done.

    ```ts
    import { createAdapter } from "@uploadcn/core"

    import { supabase } from "@/lib/supabase"

    const adapter = createAdapter(
      async ({ file, signal, onProgress }) => {
        const { path, token } = await fetch("/api/supabase-upload-url", {
          method: "POST",
          body: JSON.stringify({ name: file.name }),
          signal,
        }).then((response) => response.json())

        const { data, error } = await supabase.storage
          .from("uploads")
          .uploadToSignedUrl(path, token, file)
        if (error) throw error
        onProgress(file.size)
        return data
      },
      { name: "supabase" }
    )
    ```
  </Tab>

  <Tab value="Server action">
    Server actions can't report upload progress, so use them for small files.

    ```ts
    "use client"

    import { createAdapter } from "@uploadcn/core"

    import { saveFile } from "./actions" // "use server"

    const adapter = createAdapter(async ({ file, onProgress }) => {
      const formData = new FormData()
      formData.append("file", file)
      const result = await saveFile(formData)
      onProgress(file.size)
      return result
    })
    ```
  </Tab>
</Tabs>

## S3-compatible services [#s3-compatible-services]

MinIO, DigitalOcean Spaces, Backblaze B2, Wasabi and Google Cloud Storage (interop)
speak the S3 API. Use `s3Storage` with their `endpoint` on the server and `s3Adapter`
in the browser:

```ts
s3Storage({
  bucket: "uploads",
  region: "us-east-1",
  endpoint: "https://minio.example.com",
  accessKeyId: process.env.S3_ACCESS_KEY_ID!,
  secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
})
```


---

# Local disk (/docs/storage/filesystem)



```ts
import { createFileSystemStorage } from "@uploadcn/server/fs"
```

`createFileSystemStorage` implements the same storage interface as S3, so the browser
side doesn't change: `s3Adapter` uploads through signed URLs, with multipart and resume.
Bytes are streamed to disk, never buffered whole in memory.

<Callout type="warn" title="Node.js servers only">
  Serverless platforms (Vercel functions, Lambda, Workers) have no persistent disk. Use
  it on a VPS, a container with a volume, or locally.
</Callout>

<Steps>
  <Step>
    ### Create the storage [#create-the-storage]

    ```ts title="lib/storage.ts"
    import { createFileSystemStorage } from "@uploadcn/server/fs"

    export const files = createFileSystemStorage({
      directory: "./uploads",
      baseUrl: "/api/files",
      secret: process.env.UPLOAD_SIGNING_SECRET!, // a long random string
    })
    ```
  </Step>

  <Step>
    ### Mount the routes [#mount-the-routes]

    The upload route signs requests. The file handler receives the bytes and serves signed
    downloads.

    ```ts title="app/api/upload/route.ts"
    import { createUploadRoute } from "@uploadcn/server"

    import { files } from "@/lib/storage"

    export const { POST } = createUploadRoute({ storage: files.storage })
    ```

    ```ts title="app/api/files/route.ts"
    import { files } from "@/lib/storage"

    export const PUT = files.handler
    export const GET = files.handler
    ```
  </Step>

  <Step>
    ### Point components at it [#point-components-at-it]

    ```ts
    const adapter = s3Adapter({ endpoint: "/api/upload" })
    ```
  </Step>
</Steps>

## Public files [#public-files]

By default, `getUrl` returns a short-lived signed download URL. To serve files publicly,
for example from `public/uploads`, set `publicUrl`:

```ts
createFileSystemStorage({
  directory: "./public/uploads",
  publicUrl: "/uploads",
  baseUrl: "/api/files",
  secret: process.env.UPLOAD_SIGNING_SECRET!,
})
```

## Security [#security]

* Upload and download URLs are HMAC-signed, expire, and are bound to one method, so a
  download URL can't be used to upload.
* Object keys can't escape `directory`: `..`, absolute paths and the internal parts
  folder are rejected.
* A signed single upload must match its declared size exactly; anything larger is
  rejected while streaming.
* Files are written to a temporary path and renamed when complete, so readers never see
  half-written files.
* Downloads are served with `x-content-type-options: nosniff`.

## Options [#options]

<TypeTable
  type="{
  directory: { type: &#x22;string&#x22;, required: true, description: &#x22;Where files are written.&#x22; },
  baseUrl: { type: &#x22;string&#x22;, required: true, description: &#x22;Where `handler` is mounted.&#x22; },
  secret: { type: &#x22;string&#x22;, required: true, description: &#x22;HMAC secret for signed URLs.&#x22; },
  publicUrl: { type: &#x22;string&#x22;, description: &#x22;Serve files publicly from this URL instead of signed URLs.&#x22; },
  maxBodySize: { type: &#x22;number&#x22;, default: &#x22;5 GiB&#x22; },
  downloadExpiresIn: { type: &#x22;number&#x22;, default: &#x22;3600&#x22;, description: &#x22;Seconds.&#x22; },
}"
/>


---

# Choosing storage (/docs/storage)



UploadCN separates **where files go** from **what the UI looks like**. Components never
talk to a storage provider directly; they hand files to an *adapter*. Change the adapter
and every dropzone, button, gallery and animated component follows.

## Pick an adapter [#pick-an-adapter]

| You want…                                     | Use                                                             | Server code                |
| --------------------------------------------- | --------------------------------------------------------------- | -------------------------- |
| Your own S3 / R2 / MinIO / Spaces / B2 bucket | [`s3Adapter`](/docs/adapters/s3) + `@uploadcn/server`           | One route                  |
| Cloudinary                                    | [`cloudinaryAdapter`](/docs/storage/cloudinary)                 | None (unsigned) or one     |
| Files on your own server's disk               | [`s3Adapter`](/docs/storage/filesystem) + `@uploadcn/server/fs` | One route + a file handler |
| Your existing upload endpoint                 | [`httpAdapter`](/docs/adapters/http)                            | Yours                      |
| An SDK, Supabase, Firebase, Vercel Blob…      | [`createAdapter`](/docs/storage/custom)                         | Whatever the SDK needs     |
| Only the UI, the form submits the files       | [`localAdapter`](/docs/storage/browser)                         | None                       |
| Resumable uploads through a tus server        | [`tusAdapter`](/docs/adapters/tus)                              | A tus server               |

## Configure it once [#configure-it-once]

Wrap your app in `UploadConfigProvider`. Every component below it uses that adapter, and
any other defaults you set, like `maxSize` or `retry`.

```tsx title="components/upload-config.tsx"
"use client"

import { cloudinaryAdapter } from "@uploadcn/core"
import { UploadConfigProvider } from "@uploadcn/react"

const adapter = cloudinaryAdapter({
  cloudName: process.env.NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME!,
  uploadPreset: "user-uploads",
})

export function UploadConfig({ children }: { children: React.ReactNode }) {
  return (
    <UploadConfigProvider adapter={adapter} maxSize={20_000_000}>
      {children}
    </UploadConfigProvider>
  )
}
```

`npx shadcn@latest add @uploadcn/upload-config` creates this file for you. Put
`<UploadConfig>` in your root layout.

### Overriding per component [#overriding-per-component]

Props win over the provider, so a single component can upload somewhere else:

```tsx
<AvatarUpload adapter={s3Adapter({ endpoint: "/api/avatars" })} />
```

Providers nest, too: wrap an admin area in its own `UploadConfigProvider` to give it a
different bucket or larger limits.

<Callout title="No adapter?">
  Without a provider or an `adapter` prop, components throw an error that tells you how
  to configure one. There is no hidden default endpoint.
</Callout>

## What every adapter gets [#what-every-adapter-gets]

The engine handles the hard parts the same way for every backend:

* **Queue and concurrency**: three uploads at a time by default.
* **Retries**: network errors and 5xx/429 responses retry with backoff; 4xx don't.
* **Cancel**: the adapter receives an `AbortSignal`.
* **Progress**: the adapter reports bytes; the UI shows percent, speed and time left.
* **Resume**: adapters that save state (S3 multipart, Cloudinary chunks, tus) continue
  where they left off after a failure or a reload.


---

# Styles & theming (/docs/theming)



shadcn/ui projects are built from a **preset**: a style (Vega, Nova, Maia, Lyra, Mira,
Luma, Sera or Rhea), a base color, a theme, an icon library, a font and a radius. UploadCN
components follow all of it. Click **Customize** in the header to switch the whole site,
or paste a preset code from [ui.shadcn.com/create](https://ui.shadcn.com/create).

## Styles [#styles]

Styles change shape and density, not just color: Lyra is square and compact, Maia is
round and roomy, Sera is editorial with uppercase headings. UploadCN works the same way
shadcn/ui does:

* Parts are written with semantic classes, `cn-upload-dropzone`,
  `cn-upload-item`, `cn-upload-card`…
* Each style defines them, derived from the matching shadcn component: upload items
  from **Item**, dropzones from **Empty**, cards from **Card**, modals from **Dialog**,
  progress from **Progress**.
* The registry compiles them per style, so your files contain plain Tailwind classes,
  no runtime, no extra CSS.

<div className="not-prose my-6 grid gap-2 sm:grid-cols-2">
  <div className="rounded-xl border bg-card p-4 text-sm">
    <p className="font-medium">
      Nova
    </p>

    <code className="text-xs text-muted-foreground">
      rounded-lg text-sm gap-2.5 px-3 py-2.5
    </code>
  </div>

  <div className="rounded-xl border bg-card p-4 text-sm">
    <p className="font-medium">
      Lyra
    </p>

    <code className="text-xs text-muted-foreground">
      rounded-none text-xs gap-2.5 px-3 py-2.5
    </code>
  </div>

  <div className="rounded-xl border bg-card p-4 text-sm">
    <p className="font-medium">
      Maia
    </p>

    <code className="text-xs text-muted-foreground">
      rounded-2xl text-sm gap-3.5 px-4 py-3.5
    </code>
  </div>

  <div className="rounded-xl border bg-card p-4 text-sm">
    <p className="font-medium">
      Sera
    </p>

    <code className="text-xs text-muted-foreground">
      rounded-none uppercase tracking-wider headings
    </code>
  </div>
</div>

<p className="text-sm text-muted-foreground">
  The same upload item, compiled for four styles.
</p>

### How the right style is installed [#how-the-right-style-is-installed]

Register the namespace with a `{style}` URL (the default in
[Installation](/docs/installation)):

```json title="components.json"
{
  "registries": {
    "@uploadcn": "https://uploadcn.dev/r/{style}/{name}.json"
  }
}
```

The CLI replaces `{style}` with your project's style, like `base-lyra` or `radix-maia`,
and downloads that build. With a plain `{name}.json` URL you get Nova.

## Icons [#icons]

Components use `IconPlaceholder`, which names an icon in every library shadcn supports:

```tsx
<IconPlaceholder
  lucide="UploadIcon"
  tabler="IconUpload"
  hugeicons="Upload01Icon"
  phosphor="UploadSimpleIcon"
  remixicon="RiUploadLine"
/>
```

`shadcn add` rewrites it to an import from your `iconLibrary` and installs that package,
the same mechanism shadcn/ui's own components use.

## Colors, radius and fonts [#colors-radius-and-fonts]

Components only use theme tokens (`primary`, `muted`, `border`, `destructive`, `chart-*`…),
so base colors and themes just work. Radius comes from `--radius` (Lyra and Sera stay
square, like shadcn's own components there), and text inherits your font.

Components that need a dark surface, like
[Upload Terminal](/docs/components/upload-terminal), use a `dark` scope, so they show
your theme's dark palette rather than a fixed black.

<Callout title="Contrast in every theme">
  We scan the components with axe in every base color and theme, light and dark. All
  pass WCAG AA except one property of two palettes: in light **Olive** and **Mist**,
  shadcn's own `--muted-foreground` is 4.25:1 and 4.33:1 on white, just under 4.5:1,
  for every component that uses it. If you need AA there, darken that one variable, e.g.
  `--muted-foreground: oklch(0.52 0.031 107.3)`.
</Callout>

## Radix, Base UI and React Aria [#radix-base-ui-and-react-aria]

shadcn ships on three primitive libraries whose components don't share an API, React
Aria's `Button` takes `isDisabled` and `onPress`, its `Table` is a collection, its
`Dialog` has different parts. UploadCN only relies on what's common:

* **Buttons** are native `<button>`s styled with your own `buttonVariants`.
* **Dialogs** use the native `<dialog>` element; **popovers** the native Popover API.
* **Tabs** and **tables** are plain, accessible HTML styled with your style's tokens.
* Inputs, badges, cards and fields come from your `components/ui`.

## Keeping it that way [#keeping-it-that-way]

Every registry item is checked with [`@shadcn/lint`](https://github.com/shadcn-ui/lint)
(`no-raw-colors`, `no-unknown-classes`, `no-arbitrary-values`, `require-static-classes`),
compiled for all 8 styles, and installed into fresh Radix, Base UI and React Aria projects
by the test suite. You can run the same lint rules on your copy:

```js title="eslint.config.mjs"
import { plugin as shadcn } from "@shadcn/lint"

export default [
  {
    files: ["components/**/*.tsx"],
    plugins: { shadcn },
    rules: {
      "shadcn/no-raw-colors": "error",
      "shadcn/no-unknown-classes": "error",
    },
  },
]
```