- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace



"use client";
import type { VariantProps } from "class-variance-authority";
import { cva } from "class-variance-authority";
import * as React from "react";
import { Button } from "@/components/ui/button";
import { Shimmer } from "@/components/ui/shimmer";
import { cn } from "@/lib/utils";
const attachmentVariants = cva(
"group/attachment bg-card text-card-foreground focus-within:ring-ring/50 has-[>a,>button]:hover:bg-muted/50 data-[state=error]:border-destructive/30 relative flex w-fit max-w-full min-w-0 shrink-0 flex-wrap rounded-xl border transition-colors focus-within:ring-1 data-[state=idle]:border-dashed",
{
variants: {
orientation: {
horizontal: "min-w-40 items-center",
vertical: "w-24 flex-col has-data-[slot=attachment-content]:w-30",
},
size: {
default:
"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",
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",
xs: "gap-1.5 rounded-lg text-xs has-data-[slot=attachment-content]:px-1.5 has-data-[slot=attachment-content]:py-1 has-data-[slot=attachment-media]:p-1",
},
},
}
);
const AttachmentContext = React.createContext<{
state?: "idle" | "uploading" | "processing" | "error" | "done";
}>({});
function Attachment({
className,
state = "done",
size = "default",
orientation = "horizontal",
...props
}: React.ComponentProps<"div"> &
VariantProps<typeof attachmentVariants> & {
state?: "idle" | "uploading" | "processing" | "error" | "done";
}) {
return (
<AttachmentContext.Provider value={{ state }}>
<div
className={cn(attachmentVariants({ orientation, size }), className)}
data-orientation={orientation}
data-size={size}
data-slot="attachment"
data-state={state}
{...props}
/>
</AttachmentContext.Provider>
);
}
const attachmentMediaVariants = cva(
"bg-muted text-foreground group-data-[state=error]/attachment:bg-destructive/10 group-data-[state=error]/attachment:text-destructive relative flex aspect-square w-10 shrink-0 items-center justify-center overflow-hidden rounded-lg 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-[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",
{
defaultVariants: {
variant: "icon",
},
variants: {
variant: {
icon: "",
image:
"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",
},
},
}
);
function AttachmentMedia({
className,
variant = "icon",
...props
}: React.ComponentProps<"div"> & VariantProps<typeof attachmentMediaVariants>) {
return (
<div
className={cn(attachmentMediaVariants({ variant }), className)}
data-slot="attachment-media"
data-variant={variant}
{...props}
/>
);
}
function AttachmentContent({
className,
...props
}: React.ComponentProps<"div">) {
return (
<div
className={cn(
"max-w-full min-w-0 flex-1 text-sm leading-tight group-data-[orientation=vertical]/attachment:px-1",
className
)}
data-slot="attachment-content"
{...props}
/>
);
}
function AttachmentTitle({
className,
children,
...props
}: React.ComponentProps<"span">) {
const { state } = React.useContext(AttachmentContext);
const shimmering = state === "processing" || state === "uploading";
const content = shimmering ? <Shimmer>{children}</Shimmer> : children;
return (
<span
className={cn("block max-w-full min-w-0 truncate font-medium", className)}
data-slot="attachment-title"
{...props}
>
{content}
</span>
);
}
function AttachmentDescription({
className,
...props
}: React.ComponentProps<"span">) {
return (
<span
className={cn(
"text-muted-foreground group-data-[state=error]/attachment:text-destructive/80 mt-0.5 block min-w-0 truncate text-xs",
"max-w-full",
className
)}
data-slot="attachment-description"
{...props}
/>
);
}
function AttachmentActions({
className,
...props
}: React.ComponentProps<"div">) {
return (
<div
className={cn(
"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",
className
)}
data-slot="attachment-actions"
{...props}
/>
);
}
function AttachmentAction({
className,
variant,
size = "icon-xs",
...props
}: React.ComponentProps<typeof Button>) {
return (
<Button
className={cn(className)}
data-slot="attachment-action"
size={size}
variant={variant ?? "ghost"}
{...props}
/>
);
}
function AttachmentTrigger({
className,
as,
ref,
type,
...props
}: React.ComponentProps<"button"> & {
as?: React.ElementType;
ref?: React.Ref<HTMLButtonElement>;
}) {
const Comp = as ?? "button";
return (
<Comp
className={cn("absolute inset-0 z-10 outline-none", className)}
data-slot="attachment-trigger"
ref={ref}
type={as ? undefined : (type ?? "button")}
{...props}
/>
);
}
function AttachmentGroup({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn(
"flex min-w-0 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",
className
)}
data-slot="attachment-group"
{...props}
/>
);
}
export {
Attachment,
AttachmentAction,
AttachmentActions,
AttachmentContent,
AttachmentDescription,
AttachmentGroup,
AttachmentMedia,
AttachmentTitle,
AttachmentTrigger,
};Attachment renders a compact file card with media, title, description, and actions. It supports upload states, size variants, image thumbnails, and an overlay trigger that makes the entire card interactive.
Installation
$ bunx --bun frakment add attachment$ npx frakment add attachment$ pnpm dlx frakment add attachment$ yarn dlx frakment add attachment
Install the following dependency:
$ bun add class-variance-authority$ npm install class-variance-authority$ pnpm add class-variance-authority$ yarn add class-variance-authority
Copy and paste the following code into your project.
"use client";
import type { VariantProps } from "class-variance-authority";
import { cva } from "class-variance-authority";
import * as React from "react";
import { Button } from "@/components/ui/button";
import { Shimmer } from "@/components/ui/shimmer";
import { cn } from "@/lib/utils";
const attachmentVariants = cva(
"group/attachment bg-card text-card-foreground focus-within:ring-ring/50 has-[>a,>button]:hover:bg-muted/50 data-[state=error]:border-destructive/30 relative flex w-fit max-w-full min-w-0 shrink-0 flex-wrap rounded-xl border transition-colors focus-within:ring-1 data-[state=idle]:border-dashed",
{
variants: {
orientation: {
horizontal: "min-w-40 items-center",
vertical: "w-24 flex-col has-data-[slot=attachment-content]:w-30",
},
size: {
default:
"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",
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",
xs: "gap-1.5 rounded-lg text-xs has-data-[slot=attachment-content]:px-1.5 has-data-[slot=attachment-content]:py-1 has-data-[slot=attachment-media]:p-1",
},
},
}
);
const AttachmentContext = React.createContext<{
state?: "idle" | "uploading" | "processing" | "error" | "done";
}>({});
function Attachment({
className,
state = "done",
size = "default",
orientation = "horizontal",
...props
}: React.ComponentProps<"div"> &
VariantProps<typeof attachmentVariants> & {
state?: "idle" | "uploading" | "processing" | "error" | "done";
}) {
return (
<AttachmentContext.Provider value={{ state }}>
<div
className={cn(attachmentVariants({ orientation, size }), className)}
data-orientation={orientation}
data-size={size}
data-slot="attachment"
data-state={state}
{...props}
/>
</AttachmentContext.Provider>
);
}
const attachmentMediaVariants = cva(
"bg-muted text-foreground group-data-[state=error]/attachment:bg-destructive/10 group-data-[state=error]/attachment:text-destructive relative flex aspect-square w-10 shrink-0 items-center justify-center overflow-hidden rounded-lg 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-[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",
{
defaultVariants: {
variant: "icon",
},
variants: {
variant: {
icon: "",
image:
"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",
},
},
}
);
function AttachmentMedia({
className,
variant = "icon",
...props
}: React.ComponentProps<"div"> & VariantProps<typeof attachmentMediaVariants>) {
return (
<div
className={cn(attachmentMediaVariants({ variant }), className)}
data-slot="attachment-media"
data-variant={variant}
{...props}
/>
);
}
function AttachmentContent({
className,
...props
}: React.ComponentProps<"div">) {
return (
<div
className={cn(
"max-w-full min-w-0 flex-1 text-sm leading-tight group-data-[orientation=vertical]/attachment:px-1",
className
)}
data-slot="attachment-content"
{...props}
/>
);
}
function AttachmentTitle({
className,
children,
...props
}: React.ComponentProps<"span">) {
const { state } = React.useContext(AttachmentContext);
const shimmering = state === "processing" || state === "uploading";
const content = shimmering ? <Shimmer>{children}</Shimmer> : children;
return (
<span
className={cn("block max-w-full min-w-0 truncate font-medium", className)}
data-slot="attachment-title"
{...props}
>
{content}
</span>
);
}
function AttachmentDescription({
className,
...props
}: React.ComponentProps<"span">) {
return (
<span
className={cn(
"text-muted-foreground group-data-[state=error]/attachment:text-destructive/80 mt-0.5 block min-w-0 truncate text-xs",
"max-w-full",
className
)}
data-slot="attachment-description"
{...props}
/>
);
}
function AttachmentActions({
className,
...props
}: React.ComponentProps<"div">) {
return (
<div
className={cn(
"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",
className
)}
data-slot="attachment-actions"
{...props}
/>
);
}
function AttachmentAction({
className,
variant,
size = "icon-xs",
...props
}: React.ComponentProps<typeof Button>) {
return (
<Button
className={cn(className)}
data-slot="attachment-action"
size={size}
variant={variant ?? "ghost"}
{...props}
/>
);
}
function AttachmentTrigger({
className,
as,
ref,
type,
...props
}: React.ComponentProps<"button"> & {
as?: React.ElementType;
ref?: React.Ref<HTMLButtonElement>;
}) {
const Comp = as ?? "button";
return (
<Comp
className={cn("absolute inset-0 z-10 outline-none", className)}
data-slot="attachment-trigger"
ref={ref}
type={as ? undefined : (type ?? "button")}
{...props}
/>
);
}
function AttachmentGroup({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn(
"flex min-w-0 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",
className
)}
data-slot="attachment-group"
{...props}
/>
);
}
export {
Attachment,
AttachmentAction,
AttachmentActions,
AttachmentContent,
AttachmentDescription,
AttachmentGroup,
AttachmentMedia,
AttachmentTitle,
AttachmentTrigger,
};Update the import paths to match your project setup.
Usage
import {
Attachment,
AttachmentContent,
AttachmentDescription,
AttachmentMedia,
AttachmentTitle,
} from "@/components/ui/attachment";<Attachment>
<AttachmentMedia>
<FileTextIcon />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>report.pdf</AttachmentTitle>
<AttachmentDescription>PDF · 2.4 MB</AttachmentDescription>
</AttachmentContent>
</Attachment>Composition
Attachment
├── AttachmentMedia
├── AttachmentContent
│ ├── AttachmentTitle
│ └── AttachmentDescription
└── AttachmentActionsExamples
States
Control the visual state with the state prop. States affect color, shimmer, and action visibility.
"use client";
import {
CheckIcon,
ClockIcon,
FileTextIcon,
FileWarningIcon,
RefreshCwIcon,
XIcon,
} from "lucide-react";
import {
Attachment,
AttachmentAction,
AttachmentActions,
AttachmentContent,
AttachmentDescription,
AttachmentMedia,
AttachmentTitle,
} from "@/components/ui/attachment";
import { Spinner } from "@/components/ui/spinner";
export function AttachmentStates() {
return (
<div className="mx-auto flex w-full max-w-sm flex-col gap-2 py-12">
<Attachment className="w-full" state="idle">
<AttachmentMedia>
<ClockIcon />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>selected-file.pdf</AttachmentTitle>
<AttachmentDescription>Ready to upload</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction aria-label="Remove selected-file.pdf">
<XIcon />
</AttachmentAction>
</AttachmentActions>
</Attachment>
<Attachment className="w-full" state="uploading">
<AttachmentMedia>
<Spinner />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>design-system.zip</AttachmentTitle>
<AttachmentDescription>Uploading · 64%</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction aria-label="Cancel upload">
<XIcon />
</AttachmentAction>
</AttachmentActions>
</Attachment>
<Attachment className="w-full" state="processing">
<AttachmentMedia>
<FileTextIcon />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>market-research.pdf</AttachmentTitle>
<AttachmentDescription>Processing document</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction aria-label="Remove market-research.pdf">
<XIcon />
</AttachmentAction>
</AttachmentActions>
</Attachment>
<Attachment className="w-full" state="error">
<AttachmentMedia>
<FileWarningIcon />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>financial-model.xlsx</AttachmentTitle>
<AttachmentDescription>
Upload failed. Try again.
</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction aria-label="Retry upload">
<RefreshCwIcon />
</AttachmentAction>
<AttachmentAction aria-label="Remove financial-model.xlsx">
<XIcon />
</AttachmentAction>
</AttachmentActions>
</Attachment>
<Attachment className="w-full" state="done">
<AttachmentMedia>
<CheckIcon />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>uploaded-report.pdf</AttachmentTitle>
<AttachmentDescription>Uploaded · 1.8 MB</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction aria-label="Remove uploaded-report.pdf">
<XIcon />
</AttachmentAction>
</AttachmentActions>
</Attachment>
</div>
);
}Images
Pass variant="image" to AttachmentMedia to render a thumbnail. Combine with orientation="vertical" for a taller card.
"use client";
import { XIcon } from "lucide-react";
import {
Attachment,
AttachmentAction,
AttachmentActions,
AttachmentContent,
AttachmentDescription,
AttachmentGroup,
AttachmentMedia,
AttachmentTitle,
} from "@/components/ui/attachment";
const images = [
{
alt: "Workspace",
meta: "AVIF · 42 KB",
name: "workspace.avif",
src: "/examples/attachment/workspace.avif",
},
{
alt: "Desk",
meta: "AVIF · 14 KB",
name: "desk-reference.avif",
src: "/examples/attachment/desk-reference.avif",
},
{
alt: "Office",
meta: "AVIF · 38 KB",
name: "office-reference.avif",
src: "/examples/attachment/office-reference.avif",
},
];
export function AttachmentImage() {
return (
<div className="mx-auto w-full max-w-sm py-12">
<AttachmentGroup className="w-full">
{images.map((image) => (
<a
aria-label={`Open ${image.name}`}
className="block"
href={image.src}
key={image.name}
rel="noreferrer"
target="_blank"
>
<Attachment orientation="vertical">
<AttachmentMedia variant="image">
<img alt={image.alt} src={image.src} />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>{image.name}</AttachmentTitle>
<AttachmentDescription>{image.meta}</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction aria-label={`Remove ${image.name}`}>
<XIcon />
</AttachmentAction>
</AttachmentActions>
</Attachment>
</a>
))}
</AttachmentGroup>
</div>
);
}Group
Wrap multiple attachments in AttachmentGroup for horizontal snap scrolling. Cards keep their intrinsic width and snap on touch devices.

import {
FileCodeIcon,
FileTextIcon,
type LucideIcon,
TableIcon,
XIcon,
} from "lucide-react";
import {
Attachment,
AttachmentAction,
AttachmentActions,
AttachmentContent,
AttachmentDescription,
AttachmentGroup,
AttachmentMedia,
AttachmentTitle,
} from "@/components/ui/attachment";
interface Item {
icon?: LucideIcon;
meta: string;
name: string;
src?: string;
}
const items: Item[] = [
{ icon: FileTextIcon, meta: "PDF · 1.4 MB", name: "briefing-notes.pdf" },
{
meta: "AVIF · 39 KB",
name: "workspace.avif",
src: "/examples/attachment/workspace.avif",
},
{ icon: TableIcon, meta: "CSV · 18 KB", name: "customers.csv" },
{ icon: FileCodeIcon, meta: "TSX · 12 KB", name: "renderer.tsx" },
];
export function AttachmentGroupDemo() {
return (
<div className="mx-auto w-full max-w-sm py-12">
<AttachmentGroup className="scroll-fade-e w-full">
{items.map((item) => {
const Icon = item.icon;
return (
<Attachment className="w-64" key={item.name}>
{item.src ? (
<AttachmentMedia variant="image">
<img alt={item.name} src={item.src} />
</AttachmentMedia>
) : Icon ? (
<AttachmentMedia>
<Icon />
</AttachmentMedia>
) : null}
<AttachmentContent>
<AttachmentTitle>{item.name}</AttachmentTitle>
<AttachmentDescription>{item.meta}</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction aria-label={`Remove ${item.name}`}>
<XIcon />
</AttachmentAction>
</AttachmentActions>
</Attachment>
);
})}
</AttachmentGroup>
</div>
);
}Scroll hint
Add scroll-fade-e to AttachmentGroup so the right edge fades when more cards are off-screen. Use scroll-fade-none to opt out.
<AttachmentGroup className="scroll-fade-e">
{/* Attachment cards */}
</AttachmentGroup>Sizes
Use the size prop to change density. sm and xs reduce the media slot, padding, and description.
"use client";
import { FileTextIcon } from "lucide-react";
import {
Attachment,
AttachmentContent,
AttachmentDescription,
AttachmentMedia,
AttachmentTitle,
} from "@/components/ui/attachment";
export function AttachmentSizes() {
return (
<div className="mx-auto flex w-full max-w-sm flex-col gap-3 py-12">
<Attachment className="w-full" size="default">
<AttachmentMedia>
<FileTextIcon />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>Default attachment</AttachmentTitle>
<AttachmentDescription>PDF · 2.4 MB</AttachmentDescription>
</AttachmentContent>
</Attachment>
<Attachment className="w-full" size="sm">
<AttachmentMedia>
<FileTextIcon />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>Small attachment</AttachmentTitle>
<AttachmentDescription>PDF · 2.4 MB</AttachmentDescription>
</AttachmentContent>
</Attachment>
<Attachment className="w-full" size="xs">
<AttachmentMedia>
<FileTextIcon />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>Extra small attachment</AttachmentTitle>
</AttachmentContent>
</Attachment>
</div>
);
}Trigger
AttachmentTrigger fills the card so the entire surface is clickable while actions stay independently interactive. Pass as to render a different element, or compose it with DialogTrigger as={AttachmentTrigger} for a preview dialog.
"use client";
import { CopyIcon, FileSearchIcon, XIcon } from "lucide-react";
import {
Attachment,
AttachmentAction,
AttachmentActions,
AttachmentContent,
AttachmentDescription,
AttachmentMedia,
AttachmentTitle,
AttachmentTrigger,
} from "@/components/ui/attachment";
import {
Dialog,
DialogContent,
DialogDescription,
DialogHeader,
DialogTitle,
DialogTrigger,
} from "@/components/ui/dialog";
export function AttachmentTriggerDemo() {
return (
<div className="mx-auto w-full max-w-sm py-12">
<Dialog>
<Attachment className="w-full">
<AttachmentMedia>
<FileSearchIcon />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>research-summary.pdf</AttachmentTitle>
<AttachmentDescription>Open preview dialog</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction aria-label="Copy link">
<CopyIcon />
</AttachmentAction>
<AttachmentAction aria-label="Remove research-summary.pdf">
<XIcon />
</AttachmentAction>
</AttachmentActions>
<DialogTrigger
aria-label="Preview research-summary.pdf"
as={AttachmentTrigger}
/>
</Attachment>
<DialogContent className="sm:max-w-md">
<DialogHeader>
<DialogTitle>research-summary.pdf</DialogTitle>
<DialogDescription>
The attachment trigger fills the card and opens the dialog, while
the actions stay independently clickable above it.
</DialogDescription>
</DialogHeader>
</DialogContent>
</Dialog>
</div>
);
}<Attachment>
<AttachmentMedia>
<FileSearchIcon />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>research-summary.pdf</AttachmentTitle>
<AttachmentDescription>Open preview dialog</AttachmentDescription>
</AttachmentContent>
<AttachmentActions>
<AttachmentAction aria-label="Remove">
<XIcon />
</AttachmentAction>
</AttachmentActions>
<DialogTrigger as={AttachmentTrigger} aria-label="Preview research-summary.pdf" />
</Attachment>In Context
Upload queue
import { FileCodeIcon, FileTextIcon } from "lucide-react";
import {
Attachment,
AttachmentContent,
AttachmentDescription,
AttachmentMedia,
AttachmentTitle,
} from "@/components/ui/attachment";
import { Spinner } from "@/components/ui/spinner";
export function AttachmentUploadQueue() {
return (
<div className="border-border mx-auto flex w-full max-w-sm flex-col gap-2 rounded-lg border p-3">
<Attachment className="w-full" state="uploading">
<AttachmentMedia>
<Spinner />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>brief.pdf</AttachmentTitle>
<AttachmentDescription>Uploading · 42%</AttachmentDescription>
</AttachmentContent>
</Attachment>
<Attachment className="w-full">
<AttachmentMedia>
<FileTextIcon />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>notes.md</AttachmentTitle>
<AttachmentDescription>Markdown · 4 KB</AttachmentDescription>
</AttachmentContent>
</Attachment>
<Attachment className="w-full">
<AttachmentMedia>
<FileCodeIcon />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>renderer.tsx</AttachmentTitle>
<AttachmentDescription>TypeScript · 12 KB</AttachmentDescription>
</AttachmentContent>
</Attachment>
</div>
);
}Attachment group
import { FileCodeIcon, FileTextIcon } from "lucide-react";
import {
Attachment,
AttachmentContent,
AttachmentDescription,
AttachmentGroup,
AttachmentMedia,
AttachmentTitle,
} from "@/components/ui/attachment";
export function AttachmentGroupContext() {
return (
<AttachmentGroup className="scroll-fade-e mx-auto w-full max-w-sm">
<Attachment className="w-64">
<AttachmentMedia>
<FileTextIcon />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>report.pdf</AttachmentTitle>
<AttachmentDescription>PDF · 2.4 MB</AttachmentDescription>
</AttachmentContent>
</Attachment>
<Attachment className="w-64">
<AttachmentMedia>
<FileCodeIcon />
</AttachmentMedia>
<AttachmentContent>
<AttachmentTitle>script.ts</AttachmentTitle>
<AttachmentDescription>TypeScript · 8 KB</AttachmentDescription>
</AttachmentContent>
</Attachment>
</AttachmentGroup>
);
}API Reference
Attachment
| Prop | Type | Default | Description |
|---|---|---|---|
state | idleuploadingprocessingerrordone | — | Visual state of the attachment. |
size | defaultsmxs | — | Density of the card. |
orientation | horizontalvertical | — | Layout direction of media and content. |
AttachmentGroup
Extends React.ComponentProps<"div">. Stacks multiple attachments with horizontal snap scrolling.
AttachmentMedia
| Prop | Type | Default | Description |
|---|---|---|---|
variant | iconimage | — | Renders a thumbnail instead of an icon when set to image. |
AttachmentContent / AttachmentTitle / AttachmentDescription
Extend React.ComponentProps<"div"> / "span". AttachmentTitle truncates overflow. AttachmentDescription renders in a muted color.
AttachmentAction
Extends React.ComponentProps<typeof Button>. Requires aria-label since it renders as an icon-only button. Defaults to variant="ghost" and size="icon-xs".
AttachmentTrigger
| Prop | Type | Default | Description |
|---|---|---|---|
as | React.ElementType | — | Render as a different element or component. Accepts HTML tag names or React components. Defaults to button. |
aria-label | string | — | Required. Describes the target action (e.g. Preview report.pdf). |
Data Attributes
| Attribute | Values |
|---|---|
data-slot | attachment, attachment-media, attachment-content, attachment-title, attachment-description, attachment-actions, attachment-action, attachment-trigger, attachment-group |
data-state | idle | uploading | processing | error | done |
data-size | default | sm | xs |
data-orientation | horizontal | vertical |
data-variant | icon | image |
Accessibility
- AttachmentTrigger is an absolute overlay. Give it an
aria-labeldescribing the target action, such as "Preview report.pdf". - AttachmentAction buttons are icon-only. Every action must have an
aria-labelso screen readers can announce its intent. - Do not attach click handlers to the card itself. Use AttachmentTrigger with
as(or asDialogTriggerwithas={AttachmentTrigger}) so the click target is a real anchor or button. - Pair color with icon or text. The error state uses
file-warningand a description — never rely on color alone. - When
state="uploading", render Spinner inside AttachmentMedia and include the progress in AttachmentDescription so the state is announced.
Best Practices
- Use
statefor lifecycle, not decoration. Every state maps to a real upload phase — idle, uploading, processing, error, done. - Keep file names visible. AttachmentTitle truncates with ellipsis; do not replace it with an icon-only card.
- Use
orientation="vertical"for image attachments. Horizontal orientation reserves less vertical space but hides the image. - Prefer
AttachmentGroupfor lists. It normalizes spacing and snap behavior between cards. - Wrap with
asfor links. A plain overlay withoutasis a button with no semantic role; passas="a"for anchors or wrap inDialogTriggerwithas={AttachmentTrigger}.
Related Components
On This Page
InstallationUsageCompositionExamplesStatesImagesGroupScroll hintSizesTriggerIn ContextUpload queueAttachment groupAPI ReferenceAttachmentAttachmentGroupAttachmentMediaAttachmentContent / AttachmentTitle / AttachmentDescriptionAttachmentActionAttachmentTriggerData AttributesAccessibilityBest PracticesRelated Components