Preview
Usage
Anatomy
Attachment contains caller-owned media, a filename, honest human-readable metadata, and only the actions supported by the file state. AttachmentGroup owns horizontal scrolling, snapping, keyboard reach and conditional edge fades. AttachmentList remains the semantic vertical-list composition.
Examples
Horizontal group
Review mixed selected files in a compact horizontal group. The first file is complete and the remaining files are reachable by horizontal scroll and keyboard focus.
Small row
Use a compact row when the file sits above a composer. The completed name, known metadata, and Remove action stay on one line; the full filename remains available as the title.
Small group
Review draft files in a compact, horizontally scrollable group. Draft files include a working Remove action; the group collapses when the final file is removed.
Sent files
Read files already attached to a sent message. Sent files do not inherit draft removal controls.
Image references
Review image references with large previews. Open the filename to view the actual local image.
File row
Open a real host target through the filename or remove the file independently.
Uploading
Inspect bounded progress or indeterminate upload activity and cancel it when needed.
Failed
Read the single-line failure reason, then retry or remove the file independently. The failed card uses the semantic danger surface and border; the complete reason remains available from its accessible name and title.
Long and unknown names
Keep a long filename readable and omit metadata that is not known.
API
| Prop | Type | Default | Description |
|---|---|---|---|
filerequired | AttachmentFile | Caller-owned file identity and state. | |
media | ReactNode | Caller-owned thumbnail or preview media. | |
size | 'default' | 'sm' | 'default' | Uses a compact horizontal row for completed files. If orientation is vertical, vertical presentation wins and the default-size geometry remains. |
orientation | 'horizontal' | 'vertical' | 'horizontal' | Horizontal rows keep media beside file details. Vertical presentation wins over size='sm'. |
onRemove | (file) => void | Promise<void> | Requests removal when the current context permits it. | |
onRetry | (file) => void | Promise<void> | Requests retry of a failed upload. | |
onCancel | (file) => void | Promise<void> | Requests cancellation of an upload. | |
onOpen | (file) => void | Promise<void> | Requests opening a host-owned preview when no safe URL is used. | |
disabled | boolean | false | Disables available actions. |
| Prop | Type | Default | Description |
|---|---|---|---|
childrenrequired | ReactNode | Attachment cards in the horizontal group. | |
aria-label | string | Names the group when surrounding context is not sufficient. |
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | List items, normally one li per Attachment. |
Accessibility
Use a meaningful filename. Give AttachmentGroup or AttachmentList an accessible label when context is not clear. Filename links and host preview buttons are the only open targets; remove, retry and cancel stay separate. Uploading exposes a progressbar and a status, errors expose one truncated line with the full reason in its accessible name and title, and completion announces once when the caller changes uploading to ready. Offscreen group cards remain reachable by tabbing.
Installation
Import foundation.css once after shared tokens when using foundational controls.