# Chat Attachment

A file chip attached to a chat message, with an optional remove button.

- Category: AI & Agents
- Page: https://wunderui.com/components/chat-attachment
- Tier: Core and Pro

## Install

Chat Attachment ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { ChatAttachment, ChatAttachmentStatus, ChatAttachmentTone } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { ChatAttachment } from "@wunderui/react"

export function Attached({ onRemove }: { onRemove: () => void }) {
  return <ChatAttachment name="Q3-report.pdf" size="2.4 MB" onRemove={onRemove} />
}

export function Uploading({ progress }: { progress: number }) {
  return <ChatAttachment name="Q3-report.pdf" status="uploading" progress={progress} />
}
```

Expected result: You see a small card with a grey file tile, the name Q3-report.pdf, 2.4 MB under it and an X on the right. The second chip shows a progress bar instead of the size.

## When to use

### Use Chat Attachment for

- A file attached to a prompt before it is sent, with a remove button
- A file shown on a sent or received message, read-only
- An image or a video with a small preview and its running time
- A file that is uploading, failed to upload or is not accepted, with a Retry button

### Use something else

- [Drop Zone](https://wunderui.com/components/drop-zone) for the area where people drop or choose the files
- [Progress](https://wunderui.com/components/progress) for the progress of anything that is not a file chip, such as a job or an import
- [Chat Message](https://wunderui.com/components/chat-message) for the bubble the chip sits in

## Keyboard

The remove button and, after a failed upload, the Retry button are native buttons, so the browser handles focus and activation. The chip itself takes no focus.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or previous button, Retry before Remove, in page order. Focus shows as an indigo border with a 2 px ring. |
| `Enter` or `Space` | Presses the focused button: Remove (Cancel while uploading) calls `onRemove`, Retry calls `onRetry`. The chip does not remove itself: take the file out of your list, then move focus. |

## Behavior

What the chip does with its remove button, its text, assistive technology and motion.

- **Remove:** The chip does not hold the file. It calls the remove handler, you take the file out of your state, and the chip goes, so move focus yourself because the focused button disappears too.
- **Upload state:** Uploading swaps the size line for a progress bar, or a pulsing bar when no progress is given. Failed and unsupported turn the chip red and show a message, and Retry appears on failed only.
- **Names:** The remove button is named after the file, so every chip in a list has a name of its own. The chip is not a list item, so put chips in a labelled list.
- **Preview:** The preview image has an empty alt, because the name sits right next to it. The kind icon is hidden from assistive technology.
- **Live region:** Only the message of a failed or unsupported file is announced when it appears. A removal reaches a screen reader only through a status line that is already on the page.
- **Width:** The name and size are cut at the end, so the chip takes the width of its container. Give it a width, or put it in a flex row that can shrink.
- **States:** Hover fills the Remove button with the page tone, pressing with the subtle tone, and focus is an indigo border with a 2 px ring. The Retry button is 24 px high and follows the plain button states.
- **Motion:** The progress fill grows smoothly. With reduced motion it jumps to the new value, and an upload without progress stops pulsing.

## Anatomy

- `ChatAttachment`: A card with a 1 px border, a 4 px radius, 8 px padding and 12 px between its parts. It takes the width of its container.
- `Preview`: A 36 px tile showing the picture of an image, or of a video with a poster, and a file, image or film icon in every other case. The picture is decorative, because the name sits next to it.
- `Name`: The file name in 12 px medium text, on one line and cut at the end.
- `Size`: The size in 12 px tertiary text, on one line, which also holds the upload state such as the percentage. Without a size there is no second line.
- `Upload progress`: While uploading, a 4 px bar with an indigo fill and the rounded percentage replace the size line. The bar is a progressbar named after the file.
- `Remove button`: A 16 px round icon button named after the file, shown only when a remove handler is set. A 24 px area around it takes the press.
- `Duration`: The running time of a video: a dark badge over the poster, or text under the icon when there is no poster. Ignored for other kinds.
- `Preview`
- `Duration`
- `Progress`

## Best practices

### When to use

- Use ChatAttachment for a file attached to a message or a prompt. For a reference to a person, channel or link inside a prompt, use Context Pill.

### Do

- Pass the size already formatted with its unit, such as 2.4 MB. The chip shows it as given.
- Set the status as the upload goes: uploading, failed (add a retry handler) or unsupported for a type that is not accepted. Pass your own error text when you can say more.
- Add the remove handler only while the file can still be taken back, typically before sending. On a sent message leave it out.
- After Remove, move focus to the list or the next chip and say what was removed in a status line. The button that had focus is gone with the chip.
- Put chips in a list with an accessible name such as Attachments, so a screen reader counts them.

### Don't

- Don't pass a path as the name. It is cut at the end, so the part that tells files apart should come first, and the chip has no tooltip.
- Don't leave a failed chip without a way forward: add a retry handler or remove the chip, and say why in the error text. Red is not the only signal, since the message is text.
- Don't offer Retry for an unsupported file. It can never succeed, so ask for a different file.

## API reference

### ChatAttachment

| Prop | Type | Default | Description |
|---|---|---|---|
| name* | string |  | The file name, shown on one line and truncated at the end. It also names the remove button (`Remove <name>`). |
| className | string |  | Extra classes for the chip, for example `min-w-0 flex-1` in a flex row. |
| compact | boolean | false | Compact variant (22 px tile, thin bar, no percentage). Named `compact` because `size` already holds the file size. |
| duration | string |  | The running time of a video, for example `0:42`. Ignored for other kinds. |
| error | string |  | Replaces the message of `failed` (`Upload failed`) and `unsupported` (`This file type is not supported`). |
| kind | "file" \| "image" \| "video" | "file" | What the file is: `file` (default), `image` or `video`. It picks the icon of the tile and sets `data-kind`. |
| onRemove | () => void |  | Called when the remove button is pressed. Without it there is no button. While uploading the button cancels the upload. Take the file out of your state here and move focus. |
| onRetry | () => void |  | Shows a Retry button when `status` is `failed`. Start the upload again and set the status back to `uploading` in this handler. |
| previewSrc | string |  | The source of the picture in the tile, for an `image`, or the poster frame of a `video`. Without it the tile shows an icon. |
| progress | number |  | Upload progress from 0 to 100, used while `status` is `uploading`. Values outside the range are clamped. Without it the bar is indeterminate. |
| size | string |  | The second line, shown as given: a size such as `2.4 MB`. Leave it out for one line. Not shown while the chip is uploading, failed or unsupported. |
| status | "ready" \| "failed" \| "uploading" \| "unsupported" | "ready" | `ready` (default), `uploading` (progress bar), `failed` (red, with the message and Retry) or `unsupported` (red, with the message). |
| tone | "auto" \| "blue" \| "purple" \| "red" \| "green" \| "neutral" \| "amber" | "auto" | Tile colour. `auto` picks the tone from the file extension of `name`. Tiles with a preview image stay neutral; a failed or unsupported attachment ignores this and uses the red error style. |

## Examples

### Preview: an icon tile, an image, or the poster frame of a video

### Content: a short name, a long name that truncates, no size

### Upload state: uploading, ready, failed, unsupported

### Tile colour from the file type, compact size

## In context

### Attachment tray: uploads, a failure, retry and remove

Files upload under the prompt. Retry restarts a failed one, Remove takes a file out and moves focus to the list, and Add file starts another upload.

### Conversation: files on the question, a file in the answer

In a sent message the chip has no remove button, because the file can no longer be taken back. The conversation is a log region, so new messages are announced politely.

## For AI agents

`get_component("chat-attachment")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
