# Attachments (/docs/agent-ui/components/attachments)

Use attachments to show files as chips, with an image's preview or a file icon, the name, and the size or what's wrong with the file. The [Composer](./composer.mdx) uses them for its draft's files.

<Example caption="Press Tab to focus the chips, move between them with the arrow keys, and press Delete to remove one.">
<Basic />

```tsx
"use client";
import { useState } from "react";
import { Attachments } from "@/components/ui/attachments";

const files = [
  { id: "spec", name: "retry-spec.pdf", size: 482_000, mediaType: "application/pdf" },
  { id: "notes", name: "notes.md", size: 812, mediaType: "text/markdown" },
  { id: "dump", name: "heap.zip", size: 92_000_000, mediaType: "application/zip", error: "size" as const },
];

export default function AttachmentsExample() {
  const [items, setItems] = useState(files);

  return (
    <Attachments
      aria-label="Attachments"
      items={items}
      onRemove={(id) => setItems((current) => current.filter((item) => item.id !== id))}
    />
  );
}
```
</Example>

## Installation [#installation]

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

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

## Composition [#composition]

```text
Attachments
└── Attachment
```

`Attachments` renders a list, and an `Attachment` chip for each of its `items`. To style the chips, pass a function of `{ rows }` as its children that renders an `Attachment` per row, each with the item's `id` as its `value`. Name the list with `aria-label`.

## Usage [#usage]

### Items [#items]

Pass `items`, each with an `id`, a `name` and optionally its `size` in bytes and `mediaType`. An image shows a preview from its `url`, or from its `file` once the chip is on the page. Set `error` to `"type"` or `"size"` to show "File type not accepted" or "File is too large" in place of the size. A chip added later fades in; the ones there at first don't.

### Removing [#removing]

Pass `onRemove` to let people remove chips. It gets the item's `id`, and you take the item out of `items`. Each chip shows a remove button for the pointer, and Delete or Backspace removes the focused chip. Focus then moves to the next chip, or the previous one at the end.

A removed chip stays in place and fades out, hidden from assistive technology and out of reach, then the chips after it slide into its place. Under `prefers-reduced-motion`, or with `motion="reduced"`, it fades over 120 ms and nothing slides, and with `motion="none"` it leaves at once. To style the chips and keep the exit, pass `Attachments` a function of `{ rows }` that renders an `Attachment` for each row; chips you render from `items` leave as soon as you remove them.

### Keyboard [#keyboard]

The list takes one Tab stop. The arrow keys move between chips, and Tab leaves the list.

## API Reference [#api-reference]

### AttachmentsOptions

| Prop             | Type                                                                                          | Description                                                                                                                        |
| ---------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `items?`         | `readonly AttachmentItem[] \| undefined`                                                      | The chips, in order, keyed by `id`. Default: `[]`                                                                                  |
| `onRemove?`      | `((id: string, details: ChangeDetails<"remove-press" \| "imperative">) => void) \| undefined` | Called with an item's `id` when someone removes it. While it's set, chips can be removed.                                          |
| `focusFallback?` | `(() => HTMLElement \| null \| undefined) \| undefined`                                       | Where focus goes when a focused chip leaves and no chip is left to take it, like the composer's editor. Without it, focus is lost. |
| `motion?`        | `"auto" \| "none" \| "reduced"`                                                               | `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                                                                       |

### Agent [#agent]

An agent connected with `createAgent` reads the list's `items`. While `onRemove` is set, it can run this action:

### AttachmentsAgentActions

| Prop     | Type                                                 | Description                                                                            |
| -------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `remove` | `((id: string, event?: Event) => void) \| undefined` | Removes an item by its `id`, through `onRemove`. Offered only while `onRemove` is set. |

Removing doesn't wait for a person to confirm, since a removed file can be attached again. To ask the person first, return their answer from your `allow`, which also answers every action that does need a person. Inside a composer, an agent removes attachments through the composer's `removeAttachment`, which waits for a person while `agentConfirm` is on:

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

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

<Caption>
Runs in React and Web Components. On `<kind-attachments>`, `items` is a property and `motion` an attribute. Removal needs the `can-remove` attribute, and each removal fires `remove` with the item's `id`.
</Caption>