Attachment

A file or image attachment with its media, metadata, upload state and actions.

Office corridor with glass walls
office-corridor.pngPNG · 760 KB
Laptop on a long desk by a window
window-desk.jpgJPG · 1.3 MB
Meeting table in an open room
meeting-room.jpgJPG · 880 KB
survey-results.pdfUploading · 48%
date-parser.tsTypeScript · 9 KB
import * as stylex from "@stylexjs/stylex"
import { FileCodeIcon } from "@phosphor-icons/react/dist/csr/FileCode"
import { XIcon } from "@phosphor-icons/react/dist/csr/X"
import {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentGroup,
  AttachmentMedia,
  AttachmentTitle,
} from "@/components/ui/attachment"
import { Spinner } from "@/components/ui/spinner"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"

const styles = stylex.create({
  full: { width: "100%" },
})

const images = [
  {
    name: "office-corridor.png",
    meta: "PNG · 760 KB",
    src: "https://images.unsplash.com/photo-1497366754035-f200968a6e72?w=300&auto=format&fit=crop&q=80",
    alt: "Office corridor with glass walls",
  },
  {
    name: "window-desk.jpg",
    meta: "JPG · 1.3 MB",
    src: "https://images.unsplash.com/photo-1497215728101-856f4ea42174?w=300&auto=format&fit=crop&q=80",
    alt: "Laptop on a long desk by a window",
  },
  {
    name: "meeting-room.jpg",
    meta: "JPG · 880 KB",
    src: "https://images.unsplash.com/photo-1497366811353-6870744d04b2?w=300&auto=format&fit=crop&q=80",
    alt: "Meeting table in an open room",
  },
]

export default function AttachmentDemo() {
  return (
    <VStack gap={3} xstyle={widths.sm}>
      <AttachmentGroup>
        {images.map((image) => (
          <Attachment key={image.name} orientation="vertical">
            <AttachmentMedia variant="image">
              <img src={image.src} alt={image.alt} />
            </AttachmentMedia>
            <AttachmentContent>
              <AttachmentTitle>{image.name}</AttachmentTitle>
              <AttachmentDescription>{image.meta}</AttachmentDescription>
            </AttachmentContent>
          </Attachment>
        ))}
      </AttachmentGroup>
      <Attachment state="uploading" xstyle={styles.full}>
        <AttachmentMedia>
          <Spinner />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>survey-results.pdf</AttachmentTitle>
          <AttachmentDescription>Uploading · 48%</AttachmentDescription>
        </AttachmentContent>
        <AttachmentActions>
          <AttachmentAction aria-label="Cancel upload">
            <XIcon aria-hidden="true" />
          </AttachmentAction>
        </AttachmentActions>
      </Attachment>
      <Attachment xstyle={styles.full}>
        <AttachmentMedia>
          <FileCodeIcon aria-hidden="true" />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>date-parser.ts</AttachmentTitle>
          <AttachmentDescription>TypeScript · 9 KB</AttachmentDescription>
        </AttachmentContent>
        <AttachmentActions>
          <AttachmentAction aria-label="Remove date-parser.ts">
            <XIcon aria-hidden="true" />
          </AttachmentAction>
        </AttachmentActions>
      </Attachment>
    </VStack>
  )
}

Use an attachment for a file or an image in a chat composer, a message thread or an upload list. It shows the file's media, name and metadata, and takes actions and an upload state.

Installation

pnpm dlx shadcn@latest add @arene/attachment

Needs the arene setup first. Also adds Button.

Usage

import {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentMedia,
  AttachmentTitle,
} from "@/components/ui/attachment"
<Attachment>
  <AttachmentMedia>
    <FileTextIcon aria-hidden="true" />
  </AttachmentMedia>
  <AttachmentContent>
    <AttachmentTitle>lecture-notes.pdf</AttachmentTitle>
    <AttachmentDescription>PDF · 1.2 MB</AttachmentDescription>
  </AttachmentContent>
  <AttachmentActions>
    <AttachmentAction aria-label="Remove lecture-notes.pdf">
      <XIcon aria-hidden="true" />
    </AttachmentAction>
  </AttachmentActions>
</Attachment>

Composition

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

Use AttachmentGroup to lay out several attachments in a row that scrolls:

AttachmentGroup
├── Attachment
└── Attachment

The attachment is a flat card with a hairline edge. It passes its state and orientation to every part through context, so the media, the title and the description restyle themselves for an upload or an error.

Image

Set variant="image" on AttachmentMedia and put an img inside it. The image covers the slot. Set orientation="vertical" to put the media above the content.

Office corridor with glass walls
office-corridor.pngPNG · 760 KB
Laptop on a long desk by a window
window-desk.jpgJPG · 1.3 MB
Meeting table in an open room
meeting-room.jpgJPG · 880 KB
import { XIcon } from "@phosphor-icons/react/dist/csr/X"
import {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentGroup,
  AttachmentMedia,
  AttachmentTitle,
  AttachmentTrigger,
} from "@/components/ui/attachment"
import { widths } from "@/theme/widths"

const images = [
  {
    name: "office-corridor.png",
    meta: "PNG · 760 KB",
    src: "https://images.unsplash.com/photo-1497366754035-f200968a6e72?w=300&auto=format&fit=crop&q=80",
    alt: "Office corridor with glass walls",
  },
  {
    name: "window-desk.jpg",
    meta: "JPG · 1.3 MB",
    src: "https://images.unsplash.com/photo-1497215728101-856f4ea42174?w=300&auto=format&fit=crop&q=80",
    alt: "Laptop on a long desk by a window",
  },
  {
    name: "meeting-room.jpg",
    meta: "JPG · 880 KB",
    src: "https://images.unsplash.com/photo-1497366811353-6870744d04b2?w=300&auto=format&fit=crop&q=80",
    alt: "Meeting table in an open room",
  },
]

export default function AttachmentImage() {
  return (
    <AttachmentGroup xstyle={widths.sm}>
      {images.map((image) => (
        <Attachment key={image.name} orientation="vertical">
          <AttachmentMedia variant="image">
            <img src={image.src} alt={image.alt} />
          </AttachmentMedia>
          <AttachmentContent>
            <AttachmentTitle>{image.name}</AttachmentTitle>
            <AttachmentDescription>{image.meta}</AttachmentDescription>
          </AttachmentContent>
          <AttachmentActions>
            <AttachmentAction aria-label={`Remove ${image.name}`}>
              <XIcon aria-hidden="true" />
            </AttachmentAction>
          </AttachmentActions>
          <AttachmentTrigger
            render={
              <a
                href={image.src}
                target="_blank"
                rel="noreferrer"
                aria-label={`Open ${image.name}`}
              />
            }
          />
        </Attachment>
      ))}
    </AttachmentGroup>
  )
}

A vertical attachment is 120px wide with content and 96px with media alone. Its actions sit over the image's top corner, and AttachmentAction defaults to the outline variant there so it stays visible on a photo.

States

Set state to follow the upload. With idle the edge is dashed. uploading and processing shimmer the title. error gives the edge, fill, media and description the destructive colour. An image dims while it is not idle or done. For a percentage, put a Progress in the content, as the uploading example does.

abstract.pdfWaiting to upload
dataset.zipUploading · 48%
x
thesis-draft.pdfExtracting text
sensor-readings.xlsxThe upload failed. Retry it.
final-report.pdfUploaded · 2.2 MB
import { ArrowClockwiseIcon } from "@phosphor-icons/react/dist/csr/ArrowClockwise"
import { CheckIcon } from "@phosphor-icons/react/dist/csr/Check"
import { ClockIcon } from "@phosphor-icons/react/dist/csr/Clock"
import { FileTextIcon } from "@phosphor-icons/react/dist/csr/FileText"
import { FileXIcon } from "@phosphor-icons/react/dist/csr/FileX"
import { XIcon } from "@phosphor-icons/react/dist/csr/X"
import * as stylex from "@stylexjs/stylex"
import {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentMedia,
  AttachmentTitle,
} from "@/components/ui/attachment"
import { Progress } from "@/components/ui/progress"
import { Spinner } from "@/components/ui/spinner"
import { VStack } from "@/components/ui/stack"
import { space } from "@/theme/tokens.stylex"
import { widths } from "@/theme/widths"

const styles = stylex.create({
  full: { width: "100%" },
  progress: { paddingBlockStart: space.s1 },
})

export default function AttachmentStates() {
  return (
    <VStack gap={2} xstyle={widths.sm}>
      <Attachment state="idle" xstyle={styles.full}>
        <AttachmentMedia>
          <ClockIcon aria-hidden="true" />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>abstract.pdf</AttachmentTitle>
          <AttachmentDescription>Waiting to upload</AttachmentDescription>
        </AttachmentContent>
        <AttachmentActions>
          <AttachmentAction aria-label="Remove abstract.pdf">
            <XIcon aria-hidden="true" />
          </AttachmentAction>
        </AttachmentActions>
      </Attachment>
      <Attachment state="uploading" xstyle={styles.full}>
        <AttachmentMedia>
          <Spinner />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>dataset.zip</AttachmentTitle>
          <AttachmentDescription>Uploading · 48%</AttachmentDescription>
          <Progress value={48} aria-label="Uploading dataset.zip" xstyle={styles.progress} />
        </AttachmentContent>
        <AttachmentActions>
          <AttachmentAction aria-label="Cancel upload">
            <XIcon aria-hidden="true" />
          </AttachmentAction>
        </AttachmentActions>
      </Attachment>
      <Attachment state="processing" xstyle={styles.full}>
        <AttachmentMedia>
          <FileTextIcon aria-hidden="true" />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>thesis-draft.pdf</AttachmentTitle>
          <AttachmentDescription>Extracting text</AttachmentDescription>
        </AttachmentContent>
        <AttachmentActions>
          <AttachmentAction aria-label="Remove thesis-draft.pdf">
            <XIcon aria-hidden="true" />
          </AttachmentAction>
        </AttachmentActions>
      </Attachment>
      <Attachment state="error" xstyle={styles.full}>
        <AttachmentMedia>
          <FileXIcon aria-hidden="true" />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>sensor-readings.xlsx</AttachmentTitle>
          <AttachmentDescription>The upload failed. Retry it.</AttachmentDescription>
        </AttachmentContent>
        <AttachmentActions>
          <AttachmentAction aria-label="Retry upload">
            <ArrowClockwiseIcon aria-hidden="true" />
          </AttachmentAction>
          <AttachmentAction aria-label="Remove sensor-readings.xlsx">
            <XIcon aria-hidden="true" />
          </AttachmentAction>
        </AttachmentActions>
      </Attachment>
      <Attachment state="done" xstyle={styles.full}>
        <AttachmentMedia>
          <CheckIcon aria-hidden="true" />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>final-report.pdf</AttachmentTitle>
          <AttachmentDescription>Uploaded · 2.2 MB</AttachmentDescription>
        </AttachmentContent>
        <AttachmentActions>
          <AttachmentAction aria-label="Remove final-report.pdf">
            <XIcon aria-hidden="true" />
          </AttachmentAction>
        </AttachmentActions>
      </Attachment>
    </VStack>
  )
}

The shimmer stops under reduced motion, and the title shows in its plain colour.

Sizes

size takes default, sm or xs.

default · field-notes.pdfPDF · 1.6 MB
sm · field-notes.pdfPDF · 1.6 MB
xs · field-notes.pdf
import { FileTextIcon } from "@phosphor-icons/react/dist/csr/FileText"
import * as stylex from "@stylexjs/stylex"
import {
  Attachment,
  AttachmentContent,
  AttachmentDescription,
  AttachmentMedia,
  AttachmentTitle,
} from "@/components/ui/attachment"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"

const styles = stylex.create({
  full: { width: "100%" },
})

export default function AttachmentSizes() {
  return (
    <VStack gap={3} xstyle={widths.sm}>
      <Attachment size="default" xstyle={styles.full}>
        <AttachmentMedia>
          <FileTextIcon aria-hidden="true" />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>default · field-notes.pdf</AttachmentTitle>
          <AttachmentDescription>PDF · 1.6 MB</AttachmentDescription>
        </AttachmentContent>
      </Attachment>
      <Attachment size="sm" xstyle={styles.full}>
        <AttachmentMedia>
          <FileTextIcon aria-hidden="true" />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>sm · field-notes.pdf</AttachmentTitle>
          <AttachmentDescription>PDF · 1.6 MB</AttachmentDescription>
        </AttachmentContent>
      </Attachment>
      <Attachment size="xs" xstyle={styles.full}>
        <AttachmentMedia>
          <FileTextIcon aria-hidden="true" />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>xs · field-notes.pdf</AttachmentTitle>
        </AttachmentContent>
      </Attachment>
    </VStack>
  )
}

Group

Wrap attachments in AttachmentGroup for a row that scrolls sideways, snaps to each attachment and fades at the edge that has more to show.

lecture-notes.pdfPDF · 1.2 MB
office-corridor.png
office-corridor.pngPNG · 760 KB
measurements.csvCSV · 24 KB
solver.tsxTSX · 14 KB
import type { Icon } from "@phosphor-icons/react"
import { FileCodeIcon } from "@phosphor-icons/react/dist/csr/FileCode"
import { FileTextIcon } from "@phosphor-icons/react/dist/csr/FileText"
import { TableIcon } from "@phosphor-icons/react/dist/csr/Table"
import { XIcon } from "@phosphor-icons/react/dist/csr/X"
import * as stylex from "@stylexjs/stylex"
import {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentGroup,
  AttachmentMedia,
  AttachmentTitle,
} from "@/components/ui/attachment"
import { widths } from "@/theme/widths"

const styles = stylex.create({
  card: { width: "16rem" },
})

type Upload = { name: string; meta: string } & ({ icon: Icon } | { src: string })

const uploads: Upload[] = [
  { name: "lecture-notes.pdf", meta: "PDF · 1.2 MB", icon: FileTextIcon },
  {
    name: "office-corridor.png",
    meta: "PNG · 760 KB",
    src: "https://images.unsplash.com/photo-1497366754035-f200968a6e72?w=120&auto=format&fit=crop&q=80",
  },
  { name: "measurements.csv", meta: "CSV · 24 KB", icon: TableIcon },
  { name: "solver.tsx", meta: "TSX · 14 KB", icon: FileCodeIcon },
]

export default function AttachmentGroupDemo() {
  return (
    <AttachmentGroup xstyle={widths.sm}>
      {uploads.map((upload) => (
        <Attachment key={upload.name} xstyle={styles.card}>
          {"src" in upload ? (
            <AttachmentMedia variant="image">
              <img src={upload.src} alt={upload.name} />
            </AttachmentMedia>
          ) : (
            <AttachmentMedia>
              <upload.icon aria-hidden="true" />
            </AttachmentMedia>
          )}
          <AttachmentContent>
            <AttachmentTitle>{upload.name}</AttachmentTitle>
            <AttachmentDescription>{upload.meta}</AttachmentDescription>
          </AttachmentContent>
          <AttachmentActions>
            <AttachmentAction aria-label={`Remove ${upload.name}`}>
              <XIcon aria-hidden="true" />
            </AttachmentAction>
          </AttachmentActions>
        </Attachment>
      ))}
    </AttachmentGroup>
  )
}

Trigger

Add an AttachmentTrigger to make the whole attachment open a link or a dialog. It spans the attachment underneath the actions, so each action can still be clicked. The trigger highlights the attachment on hover and draws the focus ring around it. While the pointer is on an action, only the action highlights.

literature-review.pdfOpens a preview
import { FileMagnifyingGlassIcon } from "@phosphor-icons/react/dist/csr/FileMagnifyingGlass"
import { XIcon } from "@phosphor-icons/react/dist/csr/X"
import {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentMedia,
  AttachmentTitle,
  AttachmentTrigger,
} from "@/components/ui/attachment"
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"
import { widths } from "@/theme/widths"

export default function AttachmentTriggerDemo() {
  return (
    <Dialog>
      <Attachment xstyle={widths.sm}>
        <AttachmentMedia>
          <FileMagnifyingGlassIcon aria-hidden="true" />
        </AttachmentMedia>
        <AttachmentContent>
          <AttachmentTitle>literature-review.pdf</AttachmentTitle>
          <AttachmentDescription>Opens a preview</AttachmentDescription>
        </AttachmentContent>
        <AttachmentActions>
          <AttachmentAction aria-label="Remove literature-review.pdf">
            <XIcon aria-hidden="true" />
          </AttachmentAction>
        </AttachmentActions>
        <AttachmentTrigger aria-label="Preview literature-review.pdf" render={<DialogTrigger />} />
      </Attachment>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>literature-review.pdf</DialogTitle>
          <DialogDescription>
            The trigger fills the attachment and opens this dialog. The actions sit above it and
            stay clickable on their own.
          </DialogDescription>
        </DialogHeader>
      </DialogContent>
    </Dialog>
  )
}
<Dialog>
  <Attachment>
    {/* media, content, actions */}
    <AttachmentTrigger aria-label="Preview literature-review.pdf" render={<DialogTrigger />} />
  </Attachment>
  <DialogContent>{/* … */}</DialogContent>
</Dialog>

The dialog's trigger goes in the attachment trigger's render, not the other way round. DialogTrigger passes data-slot="dialog-trigger" to the element it renders, which would replace the attachment trigger's own slot.

Accessibility

AttachmentAction renders a Button, and AttachmentTrigger renders a button, or your element through render.

Icon-only actions

An AttachmentAction usually shows only an icon. Its aria-label should name both the action and the file.

<AttachmentAction aria-label="Remove lecture-notes.pdf">
  <XIcon aria-hidden="true" />
</AttachmentAction>

Label the trigger

AttachmentTrigger has no text of its own. Give it an aria-label that says what activating it does.

<AttachmentTrigger
  render={<a href={url} target="_blank" rel="noreferrer" aria-label="Open office-corridor.png" />}
/>

The trigger sits under the actions, so each action and the trigger can be focused and clicked on their own.

Keyboard scrolling

When the attachments in a group have a trigger or actions, keyboard users reach the ones off screen by tabbing to them. For a row of attachments with nothing to focus, give the group tabIndex={0}, role="group" and an aria-label so the row itself can be focused and scrolled.

Meaning beyond colour

The error state is a colour. Put the reason for the failure in AttachmentDescription so the state is not carried by colour alone.

API reference

Pass render to replace a part's element or compose it with another component. Every part also takes xstyle, className and style.

Attachment

Renders a div.

PropTypeDefault
state"idle" | "uploading" | "processing" | "error" | "done""done"
size"default" | "sm" | "xs""default"
orientation"horizontal" | "vertical""horizontal"

A horizontal attachment fits its content, with a 160px minimum. Pass a width through xstyle to fill a column.

AttachmentMedia

Renders a div.

PropTypeDefault
variant"icon" | "image""icon"

A square tile, 40px at default, 32px at sm and 28px at xs. In a vertical attachment it takes the full width and its icon grows to 24px. A Spinner inside it follows the icon size.

AttachmentContent

Renders a div. Holds the title and description and takes the remaining width.

AttachmentTitle

Renders a span, truncated to one line. It shimmers when state is uploading or processing.

AttachmentDescription

Renders a span at 12px, truncated to one line.

AttachmentActions

Renders a div that holds the actions above the trigger.

AttachmentAction

Renders a Button and accepts its props.

PropTypeDefault
variantButtonVariant"ghost", or "outline" in a vertical attachment
sizeButtonSize"icon-xs"

AttachmentTrigger

Renders a button with type="button" that covers the attachment, its edge included. With render, it renders your element and leaves type to you.

AttachmentGroup

Renders a div that scrolls sideways and snaps each attachment to its start.

attachmentStyles

The style maps behind the component. Spread them onto any element.

KeyWhat it is
baseThe card: fill, hairline edge, inset and radius
orientationsOne entry per orientation
sizesOne entry per size, the variables it changes
statesOne entry per state: the edge or fill
mediaThe media tile
mediaVerticalThe full-width tile of a vertical attachment
mediaErrorThe destructive tile
mediaDimmedThe dimmed image while in progress or failed
contentThe flexible column
contentVerticalThe fixed-width column of a vertical attachment
titleThe truncated title
descriptionThe truncated metadata
descriptionErrorThe destructive metadata
actionsThe actions row, above the trigger
actionsVerticalThe actions pinned over the image
triggerThe covering trigger, its hover and focus ring
groupThe scrolling, snapping row

Data attributes

AttributeOnEffect
data-slot="attachment"the rootTargets the attachment from a parent
data-statethe rootReflects state
data-sizethe rootReflects size
data-orientationthe rootReflects orientation
data-slot="attachment-media"the mediaWhere interop.css fits an image
data-variantthe mediaReflects variant
data-slot="attachment-content"the contentTargets the content from a parent
data-slot="attachment-title"the titleTargets the title from a parent
data-slot="attachment-description"the descriptionTargets the description from a parent
data-slot="attachment-actions"the actionsTargets the actions from a parent
data-slot="attachment-action"each actionTargets an action from a parent
data-slot="attachment-trigger"the triggerTargets the trigger from a parent
data-slot="attachment-group"the groupTargets the group from a parent

CSS variables

The root sets these, and each size other than default overrides some of them. Set one through style to override it. xstyle rejects a style that holds only custom properties.

VariableEffect
--arene-attachment-insetThe padding, and what the media's corner subtracts
--arene-attachment-gapThe gap between media, content and actions
--arene-attachment-radiusThe corner radius
--arene-attachment-media-sizeThe media tile's width in a horizontal attachment
--arene-attachment-icon-sizeThe icon size in the media tile