# Attachment

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

```tsx
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

**Command**

```bash
npx shadcn@latest add @arene/attachment
```

Needs the [arene setup](https://www.arene.style/docs/installation) first. Also adds [Button](https://www.arene.style/docs/components/button).

**Manual**

1. Install the packages it imports:

   ```bash
   npm install @base-ui/react @stylexjs/stylex clsx
   ```

2. Set up the token layer and the StyleX compiler, if you have not already. See
   [Installation](https://www.arene.style/docs/installation), and paste `states.ts` from the same page.
   The trigger's focus ring comes from it. Paste `shimmer.ts` from the
   [Shimmer](https://www.arene.style/docs/utilities/shimmer) page too. The title shimmers through it while
   a file uploads. The attachment also needs `interop.css`, which sizes icons, fits
   an image to the media slot and provides the group's `scroll-fade-x` and
   `no-scrollbar` classes.

3. Add the [Button](https://www.arene.style/docs/components/button). `AttachmentAction` renders it.

4. Paste this source into the file named in its title.

   ```tsx title="components/ui/attachment.tsx"
   "use client"

   import type { ComponentProps } from "react"
   import { createContext, use } from "react"
   import { useRender } from "@base-ui/react/use-render"
   import * as stylex from "@stylexjs/stylex"
   import type { StyleXStyles } from "@stylexjs/stylex"
   import { clsx } from "clsx"

   import { Button } from "@/components/ui/button"
   import { shimmerStyles } from "@/lib/shimmer"
   import { states } from "@/theme/states"
   import { color, duration, ease, layer, leading, radius, space, text } from "@/theme/tokens.stylex"

   type AttachmentState = keyof typeof stateVariants

   type AttachmentSize = keyof typeof sizes

   type AttachmentOrientation = keyof typeof orientations

   type AttachmentMediaVariant = "icon" | "image"

   const AttachmentContext = createContext<{
     state: AttachmentState
     orientation: AttachmentOrientation
   }>({ state: "done", orientation: "horizontal" })

   const destructiveEdge = `color-mix(in oklab, ${color.destructive} 30%, transparent)`

   const inProgress = (state: AttachmentState) => state === "uploading" || state === "processing"

   const styles = stylex.create({
     root: {
       position: "relative",
       isolation: "isolate",
       display: "flex",
       flexShrink: 0,
       minWidth: 0,
       maxWidth: "100%",
       "--arene-attachment-inset": space.s2,
       "--arene-attachment-gap": space.s2,
       "--arene-attachment-radius": radius.xl,
       "--arene-attachment-media-size": space.s10,
       "--arene-attachment-icon-size": space.s4,
       gap: "var(--arene-attachment-gap)",
       padding: "var(--arene-attachment-inset)",
       borderRadius: "var(--arene-attachment-radius)",
       borderWidth: 1,
       borderStyle: "solid",
       borderColor: color.border,
       backgroundColor: color.card,
       color: color.cardForeground,
       fontSize: text.sm,
       lineHeight: leading.sm,
       scrollSnapAlign: "start",
       transitionProperty: "border-color, background-color",
       transitionDuration: duration.color,
       transitionTimingFunction: ease.standard,
     },
     media: {
       display: "flex",
       flexShrink: 0,
       alignItems: "center",
       justifyContent: "center",
       width: "var(--arene-attachment-media-size)",
       aspectRatio: "1 / 1",
       overflow: "hidden",
       borderRadius: "calc(var(--arene-attachment-radius) - var(--arene-attachment-inset))",
       backgroundColor: color.muted,
       color: color.foreground,
       "--arene-icon-size": "var(--arene-attachment-icon-size)",
       transitionProperty: "opacity, background-color, color",
       transitionDuration: duration.color,
       transitionTimingFunction: ease.standard,
     },
     mediaVertical: {
       width: "100%",
       minWidth: "calc(6rem - 2 * var(--arene-attachment-inset))",
       "--arene-icon-size": space.s6,
     },
     mediaError: {
       backgroundColor: `color-mix(in oklab, ${color.destructive} 10%, transparent)`,
       color: color.destructive,
     },
     mediaDimmed: { opacity: 0.6 },
     content: {
       display: "flex",
       flexDirection: "column",
       flexGrow: 1,
       flexShrink: 1,
       flexBasis: "0%",
       rowGap: space.s0_5,
       minWidth: 0,
       maxWidth: "100%",
       paddingInline: space.s0_5,
     },
     contentVertical: {
       flexGrow: 0,
       flexBasis: "auto",
       width: "calc(7.5rem - 2 * var(--arene-attachment-inset))",
       paddingInline: space.s1,
     },
     title: {
       display: "block",
       minWidth: 0,
       maxWidth: "100%",
       overflow: "hidden",
       textOverflow: "ellipsis",
       whiteSpace: "nowrap",
       fontWeight: 500,
     },
     description: {
       display: "block",
       minWidth: 0,
       maxWidth: "100%",
       overflow: "hidden",
       textOverflow: "ellipsis",
       whiteSpace: "nowrap",
       color: color.mutedForeground,
       fontSize: text.xs,
       lineHeight: leading.xs,
     },
     descriptionError: {
       color: `color-mix(in oklab, ${color.destructive} 80%, transparent)`,
     },
     actions: {
       position: "relative",
       zIndex: layer.raised,
       display: "flex",
       flexShrink: 0,
       alignItems: "center",
       gap: space.s1,
     },
     actionsVertical: {
       position: "absolute",
       insetBlockStart: `calc(var(--arene-attachment-inset) + ${space.s1})`,
       insetInlineEnd: `calc(var(--arene-attachment-inset) + ${space.s1})`,
     },
     trigger: {
       position: "absolute",
       inset: -1,
       borderRadius: "inherit",
       backgroundColor: { default: null, ":hover": color.itemHighlightBg },
       transitionProperty: "background-color, box-shadow",
       transitionDuration: duration.color,
       transitionTimingFunction: ease.standard,
     },

     group: {
       display: "flex",
       minWidth: 0,
       gap: space.s3,
       padding: space.s1,
       overflowX: "auto",
       overscrollBehaviorX: "contain",
       scrollSnapType: "x mandatory",
       scrollPaddingInlineStart: space.s1,
       scrollPaddingInlineEnd: space.s1,
     },
   })

   const stateVariants = stylex.create({
     idle: { borderStyle: "dashed" },
     uploading: {},
     processing: {},
     error: {
       borderColor: destructiveEdge,
       backgroundColor: `color-mix(in oklab, ${color.destructive} 6%, ${color.card})`,
     },
     done: {},
   })

   const orientations = stylex.create({
     horizontal: {
       flexWrap: "wrap",
       alignItems: "center",
       width: "fit-content",
       minWidth: "10rem",
     },
     vertical: {
       flexDirection: "column",
       width: "min-content",
     },
   })

   const sizes = stylex.create({
     default: {},
     sm: {
       "--arene-attachment-inset": space.s1_5,
       "--arene-attachment-gap": space.s2_5,
       "--arene-attachment-media-size": space.s8,
       fontSize: text.xs,
       lineHeight: leading.xs,
     },
     xs: {
       "--arene-attachment-inset": space.s1,
       "--arene-attachment-gap": space.s1_5,
       "--arene-attachment-radius": radius.lg,
       "--arene-attachment-media-size": space.s7,
       "--arene-attachment-icon-size": space.s3_5,
       fontSize: text.xs,
       lineHeight: leading.xs,
     },
   })

   const attachmentStyles = {
     base: styles.root,
     orientations,
     sizes,
     states: stateVariants,
     media: styles.media,
     mediaVertical: styles.mediaVertical,
     mediaError: styles.mediaError,
     mediaDimmed: styles.mediaDimmed,
     content: styles.content,
     contentVertical: styles.contentVertical,
     title: styles.title,
     description: styles.description,
     descriptionError: styles.descriptionError,
     actions: styles.actions,
     actionsVertical: styles.actionsVertical,
     trigger: [styles.trigger, states.rowFocusRing],
     group: styles.group,
   }

   type Overrides = { xstyle?: StyleXStyles; className?: string }

   type AttachmentProps = useRender.ComponentProps<"div", { state: AttachmentState }> &
     Overrides & {
       state?: AttachmentState
       size?: AttachmentSize
       orientation?: AttachmentOrientation
     }

   function Attachment({
     render,
     ref,
     style,
     state = "done",
     size = "default",
     orientation = "horizontal",
     xstyle,
     className,
     ...props
   }: AttachmentProps) {
     const sx = stylex.props(
       styles.root,
       orientations[orientation],
       sizes[size],
       stateVariants[state],
       xstyle,
     )

     return (
       <AttachmentContext value={{ state, orientation }}>
         {useRender({
           defaultTagName: "div",
           render,
           ref,
           state: { state },
           props: {
             "data-slot": "attachment",
             "data-size": size,
             "data-orientation": orientation,
             ...sx,
             ...props,
             className: clsx(sx.className, className),
             style: { ...sx.style, ...style },
           },
         })}
       </AttachmentContext>
     )
   }

   type DivProps = useRender.ComponentProps<"div"> & Overrides

   type SpanProps = useRender.ComponentProps<"span"> & Overrides

   function AttachmentMedia({
     render,
     ref,
     style,
     variant = "icon",
     xstyle,
     className,
     ...props
   }: DivProps & { variant?: AttachmentMediaVariant }) {
     const { state, orientation } = use(AttachmentContext)
     const sx = stylex.props(
       styles.media,
       orientation === "vertical" && styles.mediaVertical,
       state === "error" && styles.mediaError,
       variant === "image" && (inProgress(state) || state === "error") && styles.mediaDimmed,
       xstyle,
     )

     return useRender({
       defaultTagName: "div",
       render,
       ref,
       props: {
         "data-slot": "attachment-media",
         "data-variant": variant,
         ...sx,
         ...props,
         className: clsx("arene-icons", sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   function AttachmentContent({ render, ref, style, xstyle, className, ...props }: DivProps) {
     const { orientation } = use(AttachmentContext)
     const sx = stylex.props(
       styles.content,
       orientation === "vertical" && styles.contentVertical,
       xstyle,
     )

     return useRender({
       defaultTagName: "div",
       render,
       ref,
       props: {
         "data-slot": "attachment-content",
         ...sx,
         ...props,
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   function AttachmentTitle({ render, ref, style, xstyle, className, ...props }: SpanProps) {
     const { state } = use(AttachmentContext)
     const sx = stylex.props(styles.title, inProgress(state) && shimmerStyles.base, xstyle)

     return useRender({
       defaultTagName: "span",
       render,
       ref,
       props: {
         "data-slot": "attachment-title",
         ...sx,
         ...props,
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   function AttachmentDescription({ render, ref, style, xstyle, className, ...props }: SpanProps) {
     const { state } = use(AttachmentContext)
     const sx = stylex.props(styles.description, state === "error" && styles.descriptionError, xstyle)

     return useRender({
       defaultTagName: "span",
       render,
       ref,
       props: {
         "data-slot": "attachment-description",
         ...sx,
         ...props,
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   function AttachmentActions({ render, ref, style, xstyle, className, ...props }: DivProps) {
     const { orientation } = use(AttachmentContext)
     const sx = stylex.props(
       styles.actions,
       orientation === "vertical" && styles.actionsVertical,
       xstyle,
     )

     return useRender({
       defaultTagName: "div",
       render,
       ref,
       props: {
         "data-slot": "attachment-actions",
         ...sx,
         ...props,
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   function AttachmentAction({ variant, size = "icon-xs", ...props }: ComponentProps<typeof Button>) {
     const { orientation } = use(AttachmentContext)

     return (
       <Button
         data-slot="attachment-action"
         variant={variant ?? (orientation === "vertical" ? "outline" : "ghost")}
         size={size}
         {...props}
       />
     )
   }

   function AttachmentTrigger({
     render,
     ref,
     style,
     xstyle,
     className,
     ...props
   }: useRender.ComponentProps<"button"> & Overrides) {
     const sx = stylex.props(styles.trigger, states.rowFocusRing, xstyle)

     return useRender({
       defaultTagName: "button",
       render,
       ref,
       props: {
         ...(render ? null : { type: "button" as const }),
         "data-slot": "attachment-trigger",
         ...sx,
         ...props,
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   function AttachmentGroup({ render, ref, style, xstyle, className, ...props }: DivProps) {
     const sx = stylex.props(styles.group, xstyle)

     return useRender({
       defaultTagName: "div",
       render,
       ref,
       props: {
         "data-slot": "attachment-group",
         ...sx,
         ...props,
         className: clsx("scroll-fade-x no-scrollbar", sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   export {
     Attachment,
     AttachmentAction,
     AttachmentActions,
     AttachmentContent,
     AttachmentDescription,
     AttachmentGroup,
     AttachmentMedia,
     AttachmentTitle,
     AttachmentTrigger,
     attachmentStyles,
     type AttachmentMediaVariant,
     type AttachmentOrientation,
     type AttachmentSize,
     type AttachmentState,
   }
   ```

5. Change the `@/` imports if your project uses different aliases.

## Usage

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

```tsx
<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

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

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

```text
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.

```tsx
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](https://www.arene.style/docs/components/progress) in the content, as the uploading example
does.

```tsx
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`.

```tsx
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.

```tsx
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.

```tsx
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>
  )
}
```

```tsx
<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](https://www.arene.style/docs/components/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.

```tsx
<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.

```tsx
<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`.

| Prop          | Type                                                         | Default        |
| ------------- | ------------------------------------------------------------ | -------------- |
| `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`.

| Prop      | Type                | Default  |
| --------- | ------------------- | -------- |
| `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](https://www.arene.style/docs/components/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](https://www.arene.style/docs/components/button) and accepts its props.

| Prop      | Type            | Default                                            |
| --------- | --------------- | -------------------------------------------------- |
| `variant` | `ButtonVariant` | `"ghost"`, or `"outline"` in a vertical attachment |
| `size`    | `ButtonSize`    | `"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.

| Key                | What it is                                      |
| ------------------ | ----------------------------------------------- |
| `base`             | The card: fill, hairline edge, inset and radius |
| `orientations`     | One entry per `orientation`                     |
| `sizes`            | One entry per `size`, the variables it changes  |
| `states`           | One entry per `state`: the edge or fill         |
| `media`            | The media tile                                  |
| `mediaVertical`    | The full-width tile of a vertical attachment    |
| `mediaError`       | The destructive tile                            |
| `mediaDimmed`      | The dimmed image while in progress or failed    |
| `content`          | The flexible column                             |
| `contentVertical`  | The fixed-width column of a vertical attachment |
| `title`            | The truncated title                             |
| `description`      | The truncated metadata                          |
| `descriptionError` | The destructive metadata                        |
| `actions`          | The actions row, above the trigger              |
| `actionsVertical`  | The actions pinned over the image               |
| `trigger`          | The covering trigger, its hover and focus ring  |
| `group`            | The scrolling, snapping row                     |

### Data attributes

| Attribute                            | On              | Effect                                |
| ------------------------------------ | --------------- | ------------------------------------- |
| `data-slot="attachment"`             | the root        | Targets the attachment from a parent  |
| `data-state`                         | the root        | Reflects `state`                      |
| `data-size`                          | the root        | Reflects `size`                       |
| `data-orientation`                   | the root        | Reflects `orientation`                |
| `data-slot="attachment-media"`       | the media       | Where `interop.css` fits an image     |
| `data-variant`                       | the media       | Reflects `variant`                    |
| `data-slot="attachment-content"`     | the content     | Targets the content from a parent     |
| `data-slot="attachment-title"`       | the title       | Targets the title from a parent       |
| `data-slot="attachment-description"` | the description | Targets the description from a parent |
| `data-slot="attachment-actions"`     | the actions     | Targets the actions from a parent     |
| `data-slot="attachment-action"`      | each action     | Targets an action from a parent       |
| `data-slot="attachment-trigger"`     | the trigger     | Targets the trigger from a parent     |
| `data-slot="attachment-group"`       | the group       | Targets 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.

| Variable                        | Effect                                             |
| ------------------------------- | -------------------------------------------------- |
| `--arene-attachment-inset`      | The padding, and what the media's corner subtracts |
| `--arene-attachment-gap`        | The gap between media, content and actions         |
| `--arene-attachment-radius`     | The corner radius                                  |
| `--arene-attachment-media-size` | The media tile's width in a horizontal attachment  |
| `--arene-attachment-icon-size`  | The icon size in the media tile                    |
