Attachment

workspace.pngPNG · 820 KB

desk-reference.jpgJPG · 1.1 MB

office-reference.jpgJPG · 940 KB

sales-dashboard.pdfUploading · 64%

message-renderer.tsxTypeScript · 12 KB

Copy

import { FileCodeIcon, XIcon } from "lucide-react"

import {

View Code

The Attachment component displays a file or image attachment, its media, name, and metadata, with optional actions and upload state. Use it for files and images in chat composers, message threads, and upload lists.

Installation#

pnpmnpmyarnbun
pnpm dlx shadcn@latest add attachment
Copy

Usage#

Copyimport {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentMedia,
  AttachmentTitle,
} from "@/components/ui/attachment"

Copy<Attachment>
  <AttachmentMedia>
    <FileTextIcon />
  </AttachmentMedia>
  <AttachmentContent>
    <AttachmentTitle>sales-dashboard.pdf</AttachmentTitle>
    <AttachmentDescription>PDF · 2.4 MB</AttachmentDescription>
  </AttachmentContent>
  <AttachmentActions>
    <AttachmentAction aria-label="Remove sales-dashboard.pdf">
      <XIcon />
    </AttachmentAction>
  </AttachmentActions>
</Attachment>

Composition#

Use the following composition to build an attachment:

CopyAttachment
├── AttachmentMedia
├── AttachmentContent
│   ├── AttachmentTitle
│   └── AttachmentDescription
├── AttachmentActions
│   └── AttachmentAction
└── AttachmentTrigger

Use AttachmentGroup to lay out multiple attachments in a scrollable row:

CopyAttachmentGroup
├── Attachment
└── Attachment

Features#

• Icon and image media through AttachmentMedia
• Upload states: idle, uploading, processing, error, and done with built-in styling and a shimmer while in progress
• Three sizes and horizontal or vertical orientation
• A full-card AttachmentTrigger that opens a link or dialog while the actions stay independently clickable
• Scrollable, snapping AttachmentGroup with an edge fade
• Customizable styling through the className prop on every part

Examples#

Image#

Set variant="image" on AttachmentMedia and render an <img> inside it. Use orientation="vertical" to stack the media above the content.

workspace.pngPNG · 820 KB

desk-reference.jpgJPG · 1.1 MB

office-reference.jpgJPG · 940 KB

Copy

import { XIcon } from "lucide-react"

import {

View Code

States#

Set state to reflect the upload lifecycle. uploading and processing shimmer the title, and error switches to a destructive treatment.

import {
  CheckIcon,
  ClockIcon,

Sizes#

Use size to switch between default, sm, and xs.

import { FileTextIcon } from "lucide-react"

import {

Group#

Wrap attachments in AttachmentGroup to lay them out in a horizontally scrollable, snapping row with an edge fade.

briefing-notes.pdfPDF · 1.4 MB

workspace.pngPNG · 820 KB

customers.csvCSV · 18 KB

renderer.tsxTSX · 12 KB

Copy

import {
  FileCodeIcon,
  FileTextIcon,

View Code

Trigger#

Add an AttachmentTrigger to make the whole card open a link or dialog. It fills the card behind the actions, so the actions stay clickable.

import { CopyIcon, FileSearchIcon, XIcon } from "lucide-react"

import {

Copy<Dialog>
  <Attachment>
    {/* media, content, actions */}
    <DialogTrigger asChild>
      <AttachmentTrigger aria-label="Preview research-summary.pdf" />
    </DialogTrigger>
  </Attachment>
  <DialogContent>{/* ... */}</DialogContent>
</Dialog>

Accessibility#

AttachmentAction renders a Button, and AttachmentTrigger renders a real <button> (or your element via asChild). Follow the guidance below so both are operable and announced.

Label icon-only actions#

AttachmentAction is usually icon-only, so give each one an aria-label describing the action and its target.

Copy<AttachmentAction aria-label="Remove sales-dashboard.pdf">
  <XIcon />
</AttachmentAction>

Label the trigger#

AttachmentTrigger covers the card with no text of its own, so give it an aria-label for what activating it does.

Copy<AttachmentTrigger asChild>
  <a
    href={url}
    target="_blank"
    rel="noreferrer"
    aria-label="Open workspace.png"
  />
</AttachmentTrigger>

The trigger sits behind the actions in the stacking order, so an AttachmentAction and the AttachmentTrigger never trap each other — both remain separately focusable and clickable.

Keyboard scrolling#

An AttachmentGroup scrolls horizontally. When its attachments are interactive: a trigger or actions, keyboard users reach off-screen items by tabbing to them. For a row of presentational attachments, make the group itself focusable and scrollable by adding tabIndex={0}, role="group", and an aria-label.

Meaning beyond color#

The error state uses a destructive color. Keep the failure reason in AttachmentDescription so the state is not conveyed by color alone.

API Reference#

Attachment#

The root attachment container.

AttachmentMedia#

The media slot for an icon or image preview.

AttachmentContent#

Wraps the title and description.

AttachmentTitle#

The attachment name. Shimmers while the attachment is uploading or processing.

AttachmentDescription#

Secondary metadata such as the file type, size, or upload status.

AttachmentActions#

A container for one or more actions, aligned to the end of the attachment.

AttachmentAction#

An action button. Renders a Button and accepts all of its props.

AttachmentTrigger#

A full-card overlay that activates the attachment. Renders a <button> by default.

AttachmentGroup#

Lays out attachments in a horizontally scrollable, snapping row.