Attachment

Displays a file or image attachment with media, metadata, upload state, and actions.

workspace.pngPNG · 820 KB

desk-reference.jpgJPG · 1.1 MB

office-reference.jpgJPG · 940 KB

sales-dashboard.pdfUploading · 64%

message-renderer.tsxTypeScript · 12 KB

1
import {
2
  Attachment,
3
  AttachmentAction,
4
  AttachmentActions,
5
  AttachmentContent,
6
  AttachmentDescription,
7
  AttachmentGroup,
8
  AttachmentMedia,
9
  AttachmentTitle,
10
} from "@/components/ui/pxl/attachment";
11
import { Spinner } from "@/components/ui/pxl/spinner";
12

13
const images = [
14
  {
15
    name: "workspace.png",
16
    meta: "PNG · 820 KB",
17
    src: "https://images.unsplash.com/photo-1497366754035-f200968a6e72?w=900&auto=format&fit=crop&q=80",
18
    alt: "Workspace",
19
  },
20
  {
21
    name: "desk-reference.jpg",
22
    meta: "JPG · 1.1 MB",
23
    src: "https://images.unsplash.com/photo-1497215728101-856f4ea42174?w=900&auto=format&fit=crop&q=80",
24
    alt: "Desk",
25
  },
26
  {
27
    name: "office-reference.jpg",
28
    meta: "JPG · 940 KB",
29
    src: "https://images.unsplash.com/photo-1497366811353-6870744d04b2?w=900&auto=format&fit=crop&q=80",
30
    alt: "Office",
31
  },
32
];
33

34
export default function AttachmentDemo() {
35
  return (
36
    <div className="mx-auto flex w-full max-w-sm flex-col gap-3 py-12">
37
      <AttachmentGroup>
38
        {images.map((image) => (
39
          <Attachment key={image.name} orientation="vertical">
40
            <AttachmentMedia variant="image">
41
              <img src={image.src} alt={image.alt} />
42
            </AttachmentMedia>
43
            <AttachmentContent>
44
              <AttachmentTitle>{image.name}</AttachmentTitle>
45
              <AttachmentDescription>{image.meta}</AttachmentDescription>
46
            </AttachmentContent>
47
          </Attachment>
48
        ))}
49
      </AttachmentGroup>
50
      <Attachment state="uploading" className="w-full">
51
        <AttachmentMedia>
52
          <Spinner />
53
        </AttachmentMedia>
54
        <AttachmentContent>
55
          <AttachmentTitle>sales-dashboard.pdf</AttachmentTitle>
56
          <AttachmentDescription>Uploading · 64%</AttachmentDescription>
57
        </AttachmentContent>
58
        <AttachmentActions>
59
          <AttachmentAction aria-label="Cancel upload">
60
            <svg
61
              xmlns="http://www.w3.org/2000/svg"
62
              fill="currentColor"
63
              viewBox="0 0 24 24"
64
            >
65
              <path d="M7 19H5v-2h2v2Zm12 0h-2v-2h2v2ZM9 15v2H7v-2h2Zm8 2h-2v-2h2v2Zm-6-2H9v-2h2v2Zm4 0h-2v-2h2v2Zm-2-2h-2v-2h2v2Zm-2-2H9V9h2v2Zm4 0h-2V9h2v2ZM9 9H7V7h2v2Zm8 0h-2V7h2v2ZM7 7H5V5h2v2Zm12 0h-2V5h2v2Z" />
66
            </svg>
67
          </AttachmentAction>
68
        </AttachmentActions>
69
      </Attachment>
70
      <Attachment className="w-full">
71
        <AttachmentMedia>
72
          <svg
73
            xmlns="http://www.w3.org/2000/svg"
74
            fill="currentColor"
75
            viewBox="0 0 24 24"
76
          >
77
            <path d="M18 22H6v-2h12v2ZM6 20H4V4h2v16ZM16 4h-2v4h4V6h2v14h-2V10h-6V4H6V2h10v2Zm0 14H8v-2h8v2Zm0-4H8v-2h8v2Zm-6-4H8V8h2v2Zm8-4h-2V4h2v2Z" />
78
          </svg>
79
        </AttachmentMedia>
80
        <AttachmentContent>
81
          <AttachmentTitle>message-renderer.tsx</AttachmentTitle>
82
          <AttachmentDescription>TypeScript · 12 KB</AttachmentDescription>
83
        </AttachmentContent>
84
        <AttachmentActions>
85
          <AttachmentAction aria-label="Remove message-renderer.tsx">
86
            <svg
87
              xmlns="http://www.w3.org/2000/svg"
88
              fill="currentColor"
89
              viewBox="0 0 24 24"
90
            >
91
              <path d="M7 19H5v-2h2v2Zm12 0h-2v-2h2v2ZM9 15v2H7v-2h2Zm8 2h-2v-2h2v2Zm-6-2H9v-2h2v2Zm4 0h-2v-2h2v2Zm-2-2h-2v-2h2v2Zm-2-2H9V9h2v2Zm4 0h-2V9h2v2ZM9 9H7V7h2v2Zm8 0h-2V7h2v2ZM7 7H5V5h2v2Zm12 0h-2V5h2v2Z" />
92
            </svg>
93
          </AttachmentAction>
94
        </AttachmentActions>
95
      </Attachment>
96
    </div>
97
  );
98
}

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.

pnpm dlx shadcn@latest add pxl-ui/registry/attachment

Install the following dependencies:

pnpm add @base-ui/react

Copy and paste the following code into your project.

1
import { mergeProps } from "@base-ui/react/merge-props";
2
import { useRender } from "@base-ui/react/use-render";
3
import { cva, type VariantProps } from "class-variance-authority";
4
import type { ComponentProps } from "react";
5

6
import { Button } from "@/components/ui/pxl/button";
7
import { cn } from "@/lib/utils";
8

9
const attachmentVariants = cva(
10
  "group/attachment relative flex w-fit max-w-full min-w-0 shrink-0 flex-wrap pixel-border pixel-size-md bg-card text-card-foreground transition-colors focus-within:ring-1 focus-within:ring-ring/30 has-[>a,>button]:hover:bg-muted/50 data-[state=error]:border-destructive/30 data-[state=idle]:border-dashed",
11
  {
12
    variants: {
13
      size: {
14
        default:
15
          "gap-2 text-sm has-data-[slot=attachment-content]:px-2.5 has-data-[slot=attachment-content]:py-2 has-data-[slot=attachment-media]:p-2",
16
        sm: "gap-2.5 text-xs has-data-[slot=attachment-content]:px-2 has-data-[slot=attachment-content]:py-1.5 has-data-[slot=attachment-media]:p-1.5",
17
        xs: "gap-1.5 rounded-xl text-xs has-data-[slot=attachment-content]:px-1.5 has-data-[slot=attachment-content]:py-1 has-data-[slot=attachment-media]:p-1",
18
      },
19
      orientation: {
20
        horizontal: "min-w-40 items-center",
21
        vertical: "w-24 flex-col has-data-[slot=attachment-content]:w-30",
22
      },
23
    },
24
  },
25
);
26

27
function Attachment({
28
  className,
29
  state = "done",
30
  size = "default",
31
  orientation = "horizontal",
32
  ...props
33
}: ComponentProps<"div"> &
34
  VariantProps<typeof attachmentVariants> & {
35
    state?: "idle" | "uploading" | "processing" | "error" | "done";
36
  }) {
37
  return (
38
    <div
39
      data-slot="attachment"
40
      data-state={state}
41
      data-size={size}
42
      data-orientation={orientation}
43
      className={cn(attachmentVariants({ size, orientation }), className)}
44
      {...props}
45
    />
46
  );
47
}
48

49
const attachmentMediaVariants = cva(
50
  "relative flex aspect-square pixel-rounded w-10 shrink-0 items-center justify-center overflow-hidden rounded-lg bg-muted text-foreground group-data-[orientation=vertical]/attachment:w-full group-data-[size=sm]/attachment:w-8 group-data-[size=xs]/attachment:w-7 group-data-[size=xs]/attachment:rounded-md group-data-[state=error]/attachment:bg-destructive/10 group-data-[state=error]/attachment:text-destructive group-data-[orientation=vertical]/attachment:*:data-[slot=spinner]:size-6! [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 group-data-[orientation=vertical]/attachment:[&_svg:not([class*='size-'])]:size-6 group-data-[size=xs]/attachment:[&_svg:not([class*='size-'])]:size-3.5",
51
  {
52
    variants: {
53
      variant: {
54
        icon: "",
55
        image:
56
          "opacity-60 group-data-[state=done]/attachment:opacity-100 group-data-[state=idle]/attachment:opacity-100 *:[img]:aspect-square *:[img]:w-full *:[img]:object-cover",
57
      },
58
    },
59
    defaultVariants: {
60
      variant: "icon",
61
    },
62
  },
63
);
64

65
function AttachmentMedia({
66
  className,
67
  variant = "icon",
68
  ...props
69
}: ComponentProps<"div"> & VariantProps<typeof attachmentMediaVariants>) {
70
  return (
71
    <div
72
      data-slot="attachment-media"
73
      data-variant={variant}
74
      className={cn(attachmentMediaVariants({ variant }), className)}
75
      {...props}
76
    />
77
  );
78
}
79

80
function AttachmentContent({ className, ...props }: ComponentProps<"div">) {
81
  return (
82
    <div
83
      data-slot="attachment-content"
84
      className={cn(
85
        "max-w-full min-w-0 flex-1 leading-tight group-data-[orientation=vertical]/attachment:px-1",
86
        className,
87
      )}
88
      {...props}
89
    />
90
  );
91
}
92

93
function AttachmentTitle({ className, ...props }: ComponentProps<"span">) {
94
  return (
95
    <span
96
      data-slot="attachment-title"
97
      className={cn(
98
        "block max-w-full min-w-0 truncate font-medium group-data-[state=processing]/attachment:shimmer group-data-[state=uploading]/attachment:shimmer",
99
        className,
100
      )}
101
      {...props}
102
    />
103
  );
104
}
105

106
function AttachmentDescription({
107
  className,
108
  ...props
109
}: ComponentProps<"span">) {
110
  return (
111
    <span
112
      data-slot="attachment-description"
113
      className={cn(
114
        "mt-0.5 block min-w-0 truncate text-xs text-muted-foreground group-data-[state=error]/attachment:text-destructive/80",
115
        "max-w-full",
116
        className,
117
      )}
118
      {...props}
119
    />
120
  );
121
}
122

123
function AttachmentActions({ className, ...props }: ComponentProps<"div">) {
124
  return (
125
    <div
126
      data-slot="attachment-actions"
127
      className={cn(
128
        "relative z-20 flex shrink-0 items-center group-data-[orientation=vertical]/attachment:absolute group-data-[orientation=vertical]/attachment:top-3 group-data-[orientation=vertical]/attachment:right-3 group-data-[orientation=vertical]/attachment:gap-1",
129
        className,
130
      )}
131
      {...props}
132
    />
133
  );
134
}
135

136
function AttachmentAction({
137
  className,
138
  variant,
139
  size = "icon-xs",
140
  ...props
141
}: ComponentProps<typeof Button>) {
142
  return (
143
    <Button
144
      data-slot="attachment-action"
145
      variant={variant ?? "ghost"}
146
      size={size}
147
      className={cn(className)}
148
      {...props}
149
    />
150
  );
151
}
152

153
function AttachmentTrigger({
154
  className,
155
  render,
156
  type,
157
  ...props
158
}: useRender.ComponentProps<"button">) {
159
  return useRender({
160
    defaultTagName: "button",
161
    props: mergeProps<"button">(
162
      {
163
        type: render ? type : (type ?? "button"),
164
        className: cn("absolute inset-0 z-10 outline-none", className),
165
      },
166
      props,
167
    ),
168
    render,
169
    state: {
170
      slot: "attachment-trigger",
171
    },
172
  });
173
}
174

175
function AttachmentGroup({ className, ...props }: ComponentProps<"div">) {
176
  return (
177
    <div
178
      data-slot="attachment-group"
179
      className={cn(
180
        "flex min-w-0 scroll-fade-x snap-x snap-mandatory scroll-px-1 scrollbar-none gap-3 overflow-x-auto overscroll-x-contain py-1 *:data-[slot=attachment]:flex-none *:data-[slot=attachment]:snap-start",
181
        className,
182
      )}
183
      {...props}
184
    />
185
  );
186
}
187

188
export {
189
  Attachment,
190
  AttachmentAction,
191
  AttachmentActions,
192
  AttachmentContent,
193
  AttachmentDescription,
194
  AttachmentGroup,
195
  AttachmentMedia,
196
  AttachmentTitle,
197
  AttachmentTrigger,
198
};

Update the import paths to match your project setup.

Usage

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

<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:

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

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

AttachmentGroup
├── 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

Image

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

States

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

Sizes

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

Group

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

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.

1
<Dialog>
2
  <Attachment>
3
    {/* media, content, actions */}
4
    <DialogTrigger
5
      render={<AttachmentTrigger aria-label="Preview research-summary.pdf" />}
6
    />
7
  </Attachment>
8
  <DialogContent>{/* ... */}</DialogContent>
9
</Dialog>

Accessibility

AttachmentAction renders a Button, and AttachmentTrigger renders a real <button> (or your element via render). 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.

1
<AttachmentAction aria-label="Remove sales-dashboard.pdf">
2
  <XIcon />
3
</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.

1
<AttachmentTrigger
2
  render={
3
    <a
4
      href={url}
5
      target="_blank"
6
      rel="noreferrer"
7
      aria-label="Open workspace.png"
8
    />
9
  }
10
/>

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.

Prop	Type	Default	Description
`state`	`"idle" \| "uploading" \| "processing" \| "error" \| "done"`	`"done"`	The upload state. Drives styling and the shimmer.
`size`	`"default" \| "sm" \| "xs"`	`"default"`	The attachment size.
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Lay the media beside or above the content.
`className`	`string`	-	Additional classes to apply to the root element.

AttachmentMedia

The media slot for an icon or image preview.

Prop	Type	Default	Description
`variant`	`"icon" \| "image"`	`"icon"`	Whether the media holds an icon or an `<img>`.
`className`	`string`	-	Additional classes to apply to the media slot.

AttachmentContent

Wraps the title and description.

Prop	Type	Default	Description
`className`	`string`	-	Additional classes to apply to the content slot.

AttachmentTitle

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

Prop	Type	Default	Description
`className`	`string`	-	Additional classes to apply to the title.

AttachmentDescription

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

Prop	Type	Default	Description
`className`	`string`	-	Additional classes to apply to the description.

AttachmentActions

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

Prop	Type	Default	Description
`className`	`string`	-	Additional classes to apply to the actions.

AttachmentAction

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

Prop	Type	Default	Description
`size`	`Button["size"]`	`"icon-xs"`	The button size.
`...props`	`React.ComponentProps<typeof Button>`	-	Props spread to the underlying `Button`.

AttachmentTrigger

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

Prop	Type	Default	Description
`render`	`ReactElement \| function`	-	Render as a different element, such as a link.
`...props`	`React.ComponentProps<"button">`	-	Props spread to the trigger element.

AttachmentGroup

Lays out attachments in a horizontally scrollable, snapping row.

Prop	Type	Default	Description
`className`	`string`	-	Additional classes to apply to the group.