# Uploader (/docs/agent-ui/components/uploader)

Use an uploader when people send files that take a while to upload. It has a drop zone with a browse button, and a row for each upload with its progress bar.

<Example caption="Drop a file or press browse to add it. Press Cancel on the report to stop it, or Retry on the failed file.">
<Basic />

```tsx
"use client";
import type { UploadItem } from "@kind-ui/agent-ui/core";
import { useState } from "react";
import { Uploader } from "@/components/ui/uploader";

const uploads: UploadItem[] = [
  { id: "report", name: "quarterly-report.pdf", size: 2_400_000, progress: 42, status: "uploading" },
  { id: "photo", name: "team-offsite.jpg", size: 3_100_000, progress: 100, status: "done" },
  { id: "dataset", name: "training-set.csv", size: 48_000_000, progress: 63, status: "error" },
];

export default function UploaderExample() {
  const [items, setItems] = useState(uploads);
  const update = (id: string, change: Partial<UploadItem>) =>
    setItems((current) => current.map((item) => (item.id === id ? { ...item, ...change } : item)));

  return (
    <Uploader
      aria-label="Uploads"
      items={items}
      onFiles={(files) =>
        setItems((current) => [
          ...current,
          ...files.map((file) => ({
            id: crypto.randomUUID(),
            name: file.name,
            size: file.size,
            progress: 0,
            status: "queued" as const,
          })),
        ])
      }
      onCancel={(id) => update(id, { status: "cancelled" })}
      onRetry={(id) => update(id, { status: "uploading", progress: 0 })}
    />
  );
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/uploader
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/uploader-web
```

## Usage [#usage]

### Uploads [#uploads]

You upload the files and own `items`. `onFiles` gets the files someone chooses, drops or pastes; add an item for each, then update its `progress` (0 to 100) and `status` as it uploads: `queued`, `uploading`, `done`, `error` or `cancelled`. Each row's progress bar is named by the file, and the line under it shows what the upload is doing and the file's size. A failed row shows the item's `error`, or "Upload failed".

When an upload finishes or fails, screen readers hear "report.pdf uploaded" or "report.pdf failed", once.

A row added later fades in. When you take an item out of `items`, its row stays in place and fades out, hidden from assistive technology and out of reach, then the rows after it slide up into its place; if its button had focus, focus moves to the next row's button first. Under `prefers-reduced-motion`, or with `motion="reduced"`, it fades over 120 ms and nothing slides, and with `motion="none"` it leaves at once.

### Limits [#limits]

Pass `accept` and `maxSize` to limit the files. The ones they rule out go to `onReject` instead of `onFiles`, each with its `reasons`.

### Cancel and Retry [#cancel-and-retry]

Pass `onCancel` to show Cancel on queued and uploading rows, and `onRetry` to show Retry on failed ones. Each gets the item's `id`. A row takes no second press until you change its `status`, so a double click can't retry and then cancel. When a cancelled row's button leaves, focus moves to the next row's button, or the one before at the end.

## API Reference [#api-reference]

### UploaderOptions

| Prop        | Type                                                                                          | Description                                                                                             |
| ----------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `items?`    | `readonly UploadItem[] \| undefined`                                                          | The uploads, in order, keyed by `id`. Default: `[]`                                                     |
| `onFiles?`  | `((files: File[], details: UploaderFilesDetails) => void) \| undefined`                       | Called with the files someone chooses, drops or pastes that pass `accept` and `maxSize`.                |
| `onReject?` | `((rejected: FileRejection[], details: UploaderFilesDetails) => void) \| undefined`           | Called with the files `accept` or `maxSize` turns down, each with its `reasons`.                        |
| `onCancel?` | `((id: string, details: ChangeDetails<"cancel-press" \| "imperative">) => void) \| undefined` | Called with an item's `id` when it's cancelled. While it's set, queued and uploading items show Cancel. |
| `onRetry?`  | `((id: string, details: ChangeDetails<"retry-press" \| "imperative">) => void) \| undefined`  | Called with an item's `id` when it's retried. While it's set, failed items show Retry.                  |
| `accept?`   | `string \| undefined`                                                                         | The file types to accept, like the `accept` attribute. Without it, any file.                            |
| `maxSize?`  | `number \| undefined`                                                                         | The largest file to accept, in bytes. Without it, any size.                                             |
| `motion?`   | `"auto" \| "none" \| "reduced"`                                                               | `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                                            |

### Agent [#agent]

An agent connected with `createAgent` reads the uploader's `items`. It can run these actions while an item can take them:

### UploaderAgentActions

| Prop     | Type                                                 | Description                                                                                             |
| -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `cancel` | `((id: string, event?: Event) => void) \| undefined` | Cancels a queued or uploading item by its `id`, through `onCancel`. Offered while one can be cancelled. |
| `retry`  | `((id: string, event?: Event) => void) \| undefined` | Retries a failed item by its `id`, through `onRetry`. Offered while one has failed.                     |

Neither action waits for a person to confirm, since a cancelled upload can be added again. To ask the person first, return their answer from your `allow`, which also answers every action that does need a person:

```ts
import { createAgent } from "@ui-sdk/react/agent";

const agent = createAgent({
  allow: ({ component, action, confirm }) => {
    if (confirm) return window.confirm(confirm);
    if (component === "kind-uploader") return window.confirm(`Let the agent ${action} an upload?`);
    return true;
  },
});
```

<Caption>
Runs in React and Web Components. On `<kind-uploader>`, `items` is a property and the other props are kebab-case attributes, so `maxSize` is `max-size`. Accepted files fire `files`, and turned-down ones `uploadreject`. Cancel and Retry need the `can-cancel` and `can-retry` attributes, and fire `uploadcancel` and `uploadretry` with the item's `id`.
</Caption>