# Attachment

A file or source as a thumbnail, chip or row, with preview, size, upload progress and remove.

```ehtml Example
import {
  Attachments, Attachment, AttachmentEmpty, createAttachment, revokeAttachment,
} from "@elements/ui/attachment";

<Attachments variant="inline">
  <Attachment e:for={f of state.files} e:key={(f) => f.id}
              data={f} hoverCard
              onRemoveItem={(f) => removeFile(state, f)} />
</Attachments>
```

## Parts

| Part | What it is |
|---|---|
| `Attachments` | The container (role=list). Its variant lays out every item inside: grid, inline or list. |
| `Attachment` | One file or source (role=listitem): preview, name, meta, progress, remove. |
| `AttachmentEmpty` | A placeholder for when there are none. Default text: No attachments. |
| `.attachment-preview` | The image or video thumbnail, or the category icon. |
| `.attachment-info` | Name and meta. Visually hidden in grid, still read by screen readers. |
| `.attachment-remove` | The remove button. Shown on hover or focus in grid and inline, always in list and on touch screens. |
| `.attachment-progress` | The upload bar (role=progressbar) along the bottom edge. |
| `.attachment-card` | The large preview inside the hover card. |

## Attributes

### Attachments

| Attribute | Type | Default | Description |
|---|---|---|---|
| `variant` | `"grid" \| "inline" \| "list"` | `"grid"` | grid: thumbnails for messages. inline: chips for a prompt input. list: rows with metadata. |
| `label` | `string` | `"Attachments"` | The list's accessible name. |
| `class` | `string` | `""` | Extra classes on the container. |
| `attrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | Other attributes for the container. |

### Attachment

| Attribute | Type | Default | Description |
|---|---|---|---|
| `data` | `AttachmentData` | (required) | The AI SDK's FileUIPart or SourceDocumentUIPart with an id, plus optional size (bytes), progress (0..100) and error. |
| `variant` | `"" \| "grid" \| "inline" \| "list"` | `""` | Empty inherits the container's variant. |
| `onRemoveItem` | `((data: AttachmentData) => void) \| undefined` | `undefined` | Set it and the remove button shows. Called with the item's data. |
| `removeLabel` | `string` | `"Remove"` | The remove button's name, followed by the file label. |
| `removeIcon` | `IconName` | `"x"` | The remove button's icon (AttachmentRemove children). |
| `showMediaType` | `boolean` | `false` | Show the media type under the name (list; read aloud in inline). |
| `showSize` | `boolean` | `false` | Show the formatted size under the name. |
| `href` | `string` | `""` | Opens the file in a new tab: a stretched link over the item, named by the label. |
| `icon` | `IconName \| ""` | `""` | Fallback icon instead of the category icon. |
| `hoverCard` | `boolean` | `false` | Show a large preview in a hover card on hover or keyboard focus. |
| `openDelay` | `number` | `0` | Hover card open delay in ms. |
| `closeDelay` | `number` | `0` | Hover card close delay in ms. |
| `hoverAlign` | `"start" \| "center" \| "end"` | `"start"` | Hover card alignment against the item. |
| `class` | `string` | `""` | Extra classes on the item. |
| `attrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | Other attributes for the item, such as data-testid. |

### AttachmentEmpty

| Attribute | Type | Default | Description |
|---|---|---|---|
| `class` | `string` | `""` | Extra classes. |

## Slots

| Slot | Part | Content |
|---|---|---|
| `default` | `Attachments` | Attachment items. |
| `default` | `Attachment` | Extra content after the info, such as an action button. |
| `default` | `AttachmentEmpty` | Replaces the text No attachments. |

## Keyboard

| Keys | Action |
|---|---|
| `Tab` | Moves to the item's link (href) or hover card trigger, then its remove button. A hidden remove button shows when focused. |
| `Enter` | Opens the link, or presses remove. |
| `Space` | Presses remove. |
| `Escape` | Closes an open hover card. |

## Data attributes

| Attribute | Values | On |
|---|---|---|
| `data-variant` | `"grid" \| "inline" \| "list"` | .attachments, .attachment |
| `data-category` | `"image" \| "video" \| "audio" \| "document" \| "source" \| "unknown"` | .attachment |
| `data-state` | `"idle" \| "uploading" \| "error"` | .attachment |
| `data-removable` | present with onRemoveItem | .attachment |

## Accessibility

- Attachments is role=list with an aria-label; each Attachment is a listitem.
- Image thumbnails take alt from the file name; video previews are muted and hidden from screen readers.
- The remove button is named "Remove report.pdf" and stays in the tab order while visually hidden.
- Upload progress is a progressbar named "Uploading report.pdf" with aria-valuenow.
- Grid hides the name and inline hides the meta visually only, so an error or progress is still read with the item.
- Removing an item from its focused remove button moves focus to the next item's remove button (the previous after the last, then the list), never to the body.
- With hoverCard, the body is focusable to open the preview, as role=img named by the file, its type and size.

## See also

- [Message](message): One chat message with avatar, author, time, streaming Markdown, attachments, actions and response branches.
- [MessageList](message-list): A conversation that stays pinned to the newest message unless the reader scrolls up.
- [PromptInput](prompt-input): A growing message composer with attachments, tools, a model picker and a send button that stops a streaming reply.