Attachment
File and image cards for uploads, with progress, states, actions, a full-card trigger and names that keep their extension.
- Chat UI components
- 9 parts
- 12 examples
@base-ui/react@tabler/icons-reactclass-variance-authority
See it in a real product: Chat Thread and Prompt Input
View blockpnpm dlx shadcn@latest add https://hextaui.com/r/attachment.jsonAdds the component, the HextaUI theme tokens and any HextaUI components it depends on.
Add the theme tokens to your global CSS, if you haven’t yet.
Install the dependencies.
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cnCopy and paste the following code into your project.
components/ui/attachment.tsx components/ui/aspect-ratio.tsx components/ui/skeleton.tsx components/ui/button.tsx components/ui/progress.tsx components/ui/scroll-area.tsx lib/motion.ts Update the import paths to match your project setup.
variant="image" on <AttachmentMedia /> shows a square thumbnail that shimmers while it loads. Set orientation="vertical" for a tile with the preview on top.
state covers the whole upload lifecycle. Idle files get a dashed border, uploading and processing titles shimmer, and errors turn the media and description red.
Pass progress while state="uploading" to draw a thin progress bar along the bottom edge. Image previews stay dimmed until the upload is done.
size scales the padding, media and text together, and keeps the inner corners concentric with the card.
Long file names truncate before the extension, so people can still tell a .pdf from a .zip. Hover the name to read it in full.
<AttachmentGroup /> lays attachments out in a row that scrolls sideways, with edges that fade and items that snap into place.
<AttachmentTrigger /> makes the whole card clickable, for example to open a preview or a link, while the actions on it stay independent. Give it an aria-label.
Files added after the page loads pop in, and the rest of the row slides over smoothly when one is removed.
When an image preview fails to load, it falls back to a file icon.
Hostile names in a narrow column, a random state every 60 ms, and 200 items in one group. Nothing overflows and the layout holds.
Media, content and actions mirror, and the progress bar fills from the start edge.
| Key | Action |
|---|---|
| Tab | Moves focus to each action, then to the trigger. Hidden actions on vertical tiles appear when focus enters the card. |
| EnterSpace | Activates the focused action or trigger. |
- While uploading, the progress bar has
role="progressbar"and is labelled by the title. - String titles get a
titleattribute with the full name, so truncated names can still be read. - Icon-only actions and the trigger have no text, so always give them an
aria-labelthat names the file. - With reduced motion on, attachments appear without popping in, the progress bar jumps instead of easing, and groups reflow instantly.
Every part except the group, the action and the trigger renders a plain element and accepts its attributes. The card styles are exported as attachmentVariants.
| Prop | Type | Default |
|---|---|---|
state | "idle" | "uploading" | "processing" | "error" | "done" | "done" |
progress0 to 100. Shown only while uploading, and clamped to that range. | number | – |
size | "default" | "sm" | "xs" | "default" |
orientation | "horizontal" | "vertical" | "horizontal" |
| Attribute | Description |
|---|---|
data-slot="attachment" | Target the card in CSS. |
data-state | The current state. |
data-size | The current size. |
data-orientation | The current orientation. |
data-slot="attachment-progress" | The progress bar, present while uploading. |
--attachment-radius | The card’s corner radius. Inner corners are derived from it. |
| Prop | Type | Default |
|---|---|---|
variantimage wraps its child in a square AspectRatio with a file icon fallback. | "icon" | "image" | "icon" |
| Attribute | Description |
|---|---|
data-slot="attachment-media" | Target the media in CSS. |
data-variant | The current variant. |
A <div> that holds the title and description and takes the remaining width.
| Attribute | Description |
|---|---|
data-slot="attachment-content" | Target the content in CSS. |
| Prop | Type | Default |
|---|---|---|
childrenA string is split so its extension never truncates. | ReactNode | – |
titleShown on hover. Defaults to the full name. | string | children |
idGenerated when omitted. The progress bar is labelled by it. | string | – |
| Attribute | Description |
|---|---|
data-slot="attachment-title" | Target the title in CSS. |
A single-line <span> for the size, type or status. It truncates when space runs out.
| Attribute | Description |
|---|---|
data-slot="attachment-description" | Target the description in CSS. |
A <div> for the action buttons. On vertical tiles it floats over the preview and, on devices with a mouse, appears on hover or focus.
| Attribute | Description |
|---|---|
data-slot="attachment-actions" | Target the actions in CSS. |
A <Button /> that sits above the trigger. It accepts every Button prop.
| Prop | Type | Default |
|---|---|---|
variant | ButtonVariant | "ghost" |
size | ButtonSize | "icon-xs" |
| Attribute | Description |
|---|---|
data-slot="attachment-action" | Target actions in CSS. |
An invisible layer that covers the whole card. Compose it with a dialog trigger, a link or any button.
| Prop | Type | Default |
|---|---|---|
render | ReactElement | (props, state) => ReactElement | <button type="button"> |
| Attribute | Description |
|---|---|
data-slot="attachment-trigger" | Target the trigger in CSS. |
A horizontal <ScrollArea /> that snaps to each attachment and animates the row when items are added or removed. It accepts every ScrollArea prop except scrollbars.
| Attribute | Description |
|---|---|
data-slot="attachment-group" | Target the group in CSS. |
data-slot="attachment-group-list" | The row that holds the attachments. |
- Aspect ratioA box that holds its shape before media loads, shimmers while loading, fades the media in and falls back when it fails.
- ButtonButtons in every variant and size, with a built-in loading, success and error flow that skips the spinner for fast requests.
- MotionThe easing curves, durations and reduced-motion check every component animates with, plus hooks for size morphs and sliding highlights.
- ProgressA bar or ring that shows how far a task has come, eases between updates and slides while the total is unknown.
- Scroll areaNative scrolling with a minimal scrollbar, edges that fade only where there’s more to see, and an optional peek that cuts the last item in half.
- BubbleChat message bubbles with variants, grouped corners, reactions and room for interactive content.
Used in Pro blocks
Blocks that build on Attachment.
Every block comes with HextaUI Pro, and Prompt Input is free.