Displays a file or image attachment with media, metadata, upload state, and actions.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { spinner } from '#components/ui/spinner.ts';
import {
attachmentClass, attachmentMediaClass, attachmentContentClass, attachmentTitleClass,
attachmentDescriptionClass, attachmentActionsClass, attachmentActionClass, attachmentGroupClass,
} from '#components/ui/attachment.ts';
import { FileCodeIcon, XIcon } from '#lib/ui/lucide.ts';
const images = [
{
name: 'workspace.png',
meta: 'PNG · 820 KB',
src: 'https://images.unsplash.com/photo-1497366754035-f200968a6e72?w=900&auto=format&fit=crop&q=80',
alt: 'Workspace',
},
{
name: 'desk-reference.jpg',
meta: 'JPG · 1.1 MB',
src: 'https://images.unsplash.com/photo-1497215728101-856f4ea42174?w=900&auto=format&fit=crop&q=80',
alt: 'Desk',
},
{
name: 'office-reference.jpg',
meta: 'JPG · 940 KB',
src: 'https://images.unsplash.com/photo-1497366811353-6870744d04b2?w=900&auto=format&fit=crop&q=80',
alt: 'Office',
},
];
export default function AttachmentDemo() {
return html`
<div class="mx-auto flex w-full max-w-sm flex-col gap-3 py-12">
<div data-slot="attachment-group" class=${attachmentGroupClass()}>
${images.map((image) => html`
<div data-slot="attachment" data-state="done" data-size="default" data-orientation="vertical" class=${attachmentClass({ orientation: 'vertical' })}>
<div data-slot="attachment-media" data-variant="image" class=${attachmentMediaClass({ variant: 'image' })}>
<img src=${image.src} alt=${image.alt}>
</div>
<div data-slot="attachment-content" class=${attachmentContentClass()}>
<span data-slot="attachment-title" class=${attachmentTitleClass()}>${image.name}</span>
<span data-slot="attachment-description" class=${attachmentDescriptionClass()}>${image.meta}</span>
</div>
</div>
`)}
</div>
<div data-slot="attachment" data-state="uploading" data-size="default" data-orientation="horizontal" class=${cn(attachmentClass(), 'w-full')}>
<div data-slot="attachment-media" data-variant="icon" class=${attachmentMediaClass()}>
${spinner()}
</div>
<div data-slot="attachment-content" class=${attachmentContentClass()}>
<span data-slot="attachment-title" class=${attachmentTitleClass()}>sales-dashboard.pdf</span>
<span data-slot="attachment-description" class=${attachmentDescriptionClass()}>Uploading · 64%</span>
</div>
<div data-slot="attachment-actions" class=${attachmentActionsClass()}>
<button type="button" data-slot="attachment-action" data-variant="ghost" data-size="icon-xs" aria-label="Cancel upload" class=${cn(buttonClass({ variant: 'ghost', size: 'icon-xs' }), attachmentActionClass())}>
${XIcon()}
</button>
</div>
</div>
<div data-slot="attachment" data-state="done" data-size="default" data-orientation="horizontal" class=${cn(attachmentClass(), 'w-full')}>
<div data-slot="attachment-media" data-variant="icon" class=${attachmentMediaClass()}>
${FileCodeIcon()}
</div>
<div data-slot="attachment-content" class=${attachmentContentClass()}>
<span data-slot="attachment-title" class=${attachmentTitleClass()}>message-renderer.tsx</span>
<span data-slot="attachment-description" class=${attachmentDescriptionClass()}>TypeScript · 12 KB</span>
</div>
<div data-slot="attachment-actions" class=${attachmentActionsClass()}>
<button type="button" data-slot="attachment-action" data-variant="ghost" data-size="icon-xs" aria-label="Remove message-renderer.tsx" class=${cn(buttonClass({ variant: 'ghost', size: 'icon-xs' }), attachmentActionClass())}>
${XIcon()}
</button>
</div>
</div>
</div>
`;
}
View Code
The attachment helpers display a file or image attachment, its media, name, and metadata, with optional actions and upload state. Use them for files and images in chat composers, message threads, and upload lists.
Installation
Copy and paste the following code into your project.
/**
* Attachment: a file or image attached to a message or a form, as a compact
* card with its media, name, details and actions. Tier-1 class helper;
* compose with plain elements.
*
* shadcn parity:
* AttachmentGroup → attachmentGroupClass()
* Attachment (variant, size) → attachmentClass({ ... }), alias attachmentVariants
* AttachmentMedia → attachmentMediaClass({ ... }), alias attachmentMediaVariants
* AttachmentContent / AttachmentTitle / AttachmentDescription
* → attachmentContentClass() / attachmentTitleClass() / attachmentDescriptionClass()
* AttachmentActions / AttachmentAction / AttachmentTrigger
* → attachmentActionsClass() / attachmentActionClass() / attachmentTriggerClass()
*
* Every part takes its `data-slot`, which the styles key on.
*
* A11y (required for accessible output): the file name is the attachment's
* accessible name, so keep it in real text (the title), not only in an image.
* An image preview needs `alt` (or `alt=""` when the title already names it).
* Each icon-only action (remove, download) is a `<button>` with an
* `aria-label` naming the file ("Remove report.pdf"), and a trigger that opens
* the file is a real link or button.
*
* Design tokens used: --border, --muted, --muted-foreground, --background.
*
* @example
* ```html
* <div class=${attachmentClass()} data-slot="attachment">
* <div class=${attachmentContentClass()} data-slot="attachment-content">
* <span class=${attachmentTitleClass()} data-slot="attachment-title">report.pdf</span>
* <span class=${attachmentDescriptionClass()} data-slot="attachment-description">2.4 MB</span>
* </div>
* </div>
* ```
*/
import { cn } from '../lib/utils.ts';
const ATTACHMENT_BASE =
'w-fit rounded-xl focus-within:ring-1 focus-within:ring-ring/50 group/attachment relative flex max-w-full min-w-0 shrink-0 flex-wrap border bg-card text-card-foreground transition-colors has-[>a,>button]:hover:bg-muted/50 data-[state=error]:border-destructive/30 data-[state=idle]:border-dashed';
const ATTACHMENT_SIZES = {
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',
} as const;
const ATTACHMENT_ORIENTATIONS = {
horizontal: 'min-w-40 items-center',
vertical: 'w-24 has-data-[slot=attachment-content]:w-30 flex-col',
} as const;
/** The part, with its variant options. Set its `data-slot` and any `data-variant` / `data-size` to match. */
export function attachmentClass(opts: { size?: keyof typeof ATTACHMENT_SIZES; orientation?: keyof typeof ATTACHMENT_ORIENTATIONS } & { className?: string } = {}): string {
return cn(ATTACHMENT_BASE, ATTACHMENT_SIZES[opts.size ?? 'default'], ATTACHMENT_ORIENTATIONS[opts.orientation ?? 'horizontal'], opts.className);
}
/**
* shadcn's name for {@link attachmentClass}, so shadcn code ports verbatim. Like cva,
* it merges a `className` into the result.
*/
export function attachmentVariants(opts: { size?: keyof typeof ATTACHMENT_SIZES; orientation?: keyof typeof ATTACHMENT_ORIENTATIONS } & { className?: string } = {}): string {
return attachmentClass(opts);
}
const ATTACHMENT_MEDIA_BASE =
"w-10 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-[orientation=vertical]/attachment:*:data-[slot=spinner]:size-6! [&_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 relative flex aspect-square shrink-0 items-center justify-center overflow-hidden group-data-[state=error]/attachment:bg-destructive/10 group-data-[state=error]/attachment:text-destructive [&_svg]:pointer-events-none";
const ATTACHMENT_MEDIA_VARIANTS = {
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',
} as const;
/** The part, with its variant options. Set its `data-slot` and any `data-variant` / `data-size` to match. */
export function attachmentMediaClass(opts: { variant?: keyof typeof ATTACHMENT_MEDIA_VARIANTS } & { className?: string } = {}): string {
return cn(ATTACHMENT_MEDIA_BASE, ATTACHMENT_MEDIA_VARIANTS[opts.variant ?? 'icon'], opts.className);
}
/**
* shadcn's name for {@link attachmentMediaClass}, so shadcn code ports verbatim. Like cva,
* it merges a `className` into the result.
*/
export function attachmentMediaVariants(opts: { variant?: keyof typeof ATTACHMENT_MEDIA_VARIANTS } & { className?: string } = {}): string {
return attachmentMediaClass(opts);
}
/** Set `data-slot="attachment-content"` on the element. */
export function attachmentContentClass(): string {
return 'leading-tight group-data-[orientation=vertical]/attachment:px-1 max-w-full min-w-0 flex-1';
}
/** Set `data-slot="attachment-title"` on the element. */
export function attachmentTitleClass(): string {
return 'font-medium block max-w-full min-w-0 truncate group-data-[state=processing]/attachment:shimmer group-data-[state=uploading]/attachment:shimmer';
}
/** Set `data-slot="attachment-description"` on the element. */
export function attachmentDescriptionClass(): string {
return 'mt-0.5 text-xs block min-w-0 truncate text-muted-foreground group-data-[state=error]/attachment:text-destructive/80';
}
/** Set `data-slot="attachment-actions"` on the element. */
export function attachmentActionsClass(): string {
return 'relative z-20 group-data-[orientation=vertical]/attachment:absolute group-data-[orientation=vertical]/attachment:top-3 group-data-[orientation=vertical]/attachment:end-3 group-data-[orientation=vertical]/attachment:gap-1 flex shrink-0 items-center';
}
/** Set `data-slot="attachment-action"` on the element. */
export function attachmentActionClass(): string {
return '';
}
/** Set `data-slot="attachment-trigger"` on the element. */
export function attachmentTriggerClass(): string {
return 'absolute inset-0 z-10 outline-none';
}
/** Set `data-slot="attachment-group"` on the element. */
export function attachmentGroupClass(): string {
return 'scroll-px-1 gap-3 py-1 flex min-w-0 scroll-fade-x snap-x snap-mandatory scrollbar-none overflow-x-auto overscroll-x-contain *:data-[slot=attachment]:flex-none *:data-[slot=attachment]:snap-start';
}
Update the import paths to match your project setup.
Usage
import {
attachmentClass,
attachmentMediaClass,
attachmentContentClass,
attachmentTitleClass,
attachmentDescriptionClass,
attachmentActionsClass,
attachmentActionClass,
} from '#components/ui/attachment.ts';
<div data-slot="attachment" data-state="done" data-size="default" data-orientation="horizontal" class=${attachmentClass()}>
<div data-slot="attachment-media" data-variant="icon" class=${attachmentMediaClass()}>
${FileTextIcon()}
</div>
<div data-slot="attachment-content" class=${attachmentContentClass()}>
<span data-slot="attachment-title" class=${attachmentTitleClass()}>sales-dashboard.pdf</span>
<span data-slot="attachment-description" class=${attachmentDescriptionClass()}>PDF · 2.4 MB</span>
</div>
<div data-slot="attachment-actions" class=${attachmentActionsClass()}>
<button type="button" data-slot="attachment-action" aria-label="Remove sales-dashboard.pdf"
class=${cn(buttonClass({ variant: 'ghost', size: 'icon-xs' }), attachmentActionClass())}>
${XIcon()}
</button>
</div>
</div>
Composition
Use the following composition to build an attachment:
Attachment
├── AttachmentMedia
├── AttachmentContent
│ ├── AttachmentTitle
│ └── AttachmentDescription
├── AttachmentActions
│ └── AttachmentAction
└── AttachmentTrigger
Each part is a plain element carrying its helper's classes and its data-slot, which the styles key on. Use attachmentGroupClass() to lay out multiple attachments in a scrollable row:
AttachmentGroup
├── Attachment
└── Attachment
Features
- Icon and image media through
attachmentMediaClass() - Upload states:
idle,uploading,processing,error, anddonewith built-in styling and a shimmer while in progress - Three sizes and horizontal or vertical orientation
- A full-card trigger that opens a link or dialog while the actions stay independently clickable
- A scrollable, snapping group with an edge fade
- Customizable styling by merging your own classes into any part with
cn()
Image
Pass variant: 'image' to attachmentMediaClass() (with data-variant="image") and render an <img> inside it. Use orientation: 'vertical' to stack the media above the content.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
attachmentClass, attachmentMediaClass, attachmentContentClass, attachmentTitleClass,
attachmentDescriptionClass, attachmentActionsClass, attachmentActionClass, attachmentTriggerClass,
attachmentGroupClass,
} from '#components/ui/attachment.ts';
import { XIcon } from '#lib/ui/lucide.ts';
const images = [
{
name: 'workspace.png',
meta: 'PNG · 820 KB',
src: 'https://images.unsplash.com/photo-1497366754035-f200968a6e72?w=900&auto=format&fit=crop&q=80',
alt: 'Workspace',
},
{
name: 'desk-reference.jpg',
meta: 'JPG · 1.1 MB',
src: 'https://images.unsplash.com/photo-1497215728101-856f4ea42174?w=900&auto=format&fit=crop&q=80',
alt: 'Desk',
},
{
name: 'office-reference.jpg',
meta: 'JPG · 940 KB',
src: 'https://images.unsplash.com/photo-1497366811353-6870744d04b2?w=900&auto=format&fit=crop&q=80',
alt: 'Office',
},
];
export default function AttachmentImage() {
return html`
<div class="mx-auto w-full max-w-sm py-12">
<div data-slot="attachment-group" class=${cn(attachmentGroupClass(), 'w-full')}>
${images.map((image) => html`
<div data-slot="attachment" data-state="done" data-size="default" data-orientation="vertical" class=${attachmentClass({ orientation: 'vertical' })}>
<div data-slot="attachment-media" data-variant="image" class=${attachmentMediaClass({ variant: 'image' })}>
<img src=${image.src} alt=${image.alt}>
</div>
<div data-slot="attachment-content" class=${attachmentContentClass()}>
<span data-slot="attachment-title" class=${attachmentTitleClass()}>${image.name}</span>
<span data-slot="attachment-description" class=${attachmentDescriptionClass()}>${image.meta}</span>
</div>
<div data-slot="attachment-actions" class=${attachmentActionsClass()}>
<button type="button" data-slot="attachment-action" data-variant="ghost" data-size="icon-xs" aria-label=${`Remove ${image.name}`} class=${cn(buttonClass({ variant: 'ghost', size: 'icon-xs' }), attachmentActionClass())}>
${XIcon()}
</button>
</div>
<a data-slot="attachment-trigger" href=${image.src} target="_blank" rel="noreferrer" aria-label=${`Open ${image.name}`} class=${attachmentTriggerClass()}></a>
</div>
`)}
</div>
</div>
`;
}
View Code
States
Set data-state to reflect the upload lifecycle. uploading and processing shimmer the title, and error switches to a destructive treatment.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { spinner } from '#components/ui/spinner.ts';
import {
attachmentClass, attachmentMediaClass, attachmentContentClass, attachmentTitleClass,
attachmentDescriptionClass, attachmentActionsClass, attachmentActionClass,
} from '#components/ui/attachment.ts';
import {
CheckIcon, ClockIcon, FileTextIcon, FileWarningIcon, RefreshCwIcon, XIcon,
} from '#lib/ui/lucide.ts';
type State = 'idle' | 'uploading' | 'processing' | 'error' | 'done';
const action = (label: string, icon: unknown) => html`
<button type="button" data-slot="attachment-action" data-variant="ghost" data-size="icon-xs" aria-label=${label} class=${cn(buttonClass({ variant: 'ghost', size: 'icon-xs' }), attachmentActionClass())}>
${icon}
</button>
`;
const attachment = (state: State, media: unknown, title: string, description: string, actions: unknown) => html`
<div data-slot="attachment" data-state=${state} data-size="default" data-orientation="horizontal" class=${cn(attachmentClass(), 'w-full')}>
<div data-slot="attachment-media" data-variant="icon" class=${attachmentMediaClass()}>
${media}
</div>
<div data-slot="attachment-content" class=${attachmentContentClass()}>
<span data-slot="attachment-title" class=${attachmentTitleClass()}>${title}</span>
<span data-slot="attachment-description" class=${attachmentDescriptionClass()}>${description}</span>
</div>
<div data-slot="attachment-actions" class=${attachmentActionsClass()}>
${actions}
</div>
</div>
`;
export default function AttachmentStates() {
return html`
<div class="mx-auto flex w-full max-w-sm flex-col gap-2 py-12">
${attachment('idle', ClockIcon(), 'selected-file.pdf', 'Ready to upload',
action('Remove selected-file.pdf', XIcon()))}
${attachment('uploading', spinner(), 'design-system.zip', 'Uploading · 64%',
action('Cancel upload', XIcon()))}
${attachment('processing', FileTextIcon(), 'market-research.pdf', 'Processing document',
action('Remove market-research.pdf', XIcon()))}
${attachment('error', FileWarningIcon(), 'financial-model.xlsx', 'Upload failed. Try again.', html`
${action('Retry upload', RefreshCwIcon())}
${action('Remove financial-model.xlsx', XIcon())}
`)}
${attachment('done', CheckIcon(), 'uploaded-report.pdf', 'Uploaded · 1.8 MB',
action('Remove uploaded-report.pdf', XIcon()))}
</div>
`;
}
View Code
Sizes
Use the size option (with a matching data-size) to switch between default, sm, and xs.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
attachmentClass, attachmentMediaClass, attachmentContentClass, attachmentTitleClass,
attachmentDescriptionClass,
} from '#components/ui/attachment.ts';
import { FileTextIcon } from '#lib/ui/lucide.ts';
export default function AttachmentSizes() {
return html`
<div class="mx-auto flex w-full max-w-sm flex-col gap-3 py-12">
<div data-slot="attachment" data-state="done" data-size="default" data-orientation="horizontal" class=${cn(attachmentClass({ size: 'default' }), 'w-full')}>
<div data-slot="attachment-media" data-variant="icon" class=${attachmentMediaClass()}>
${FileTextIcon()}
</div>
<div data-slot="attachment-content" class=${attachmentContentClass()}>
<span data-slot="attachment-title" class=${attachmentTitleClass()}>Default attachment</span>
<span data-slot="attachment-description" class=${attachmentDescriptionClass()}>PDF · 2.4 MB</span>
</div>
</div>
<div data-slot="attachment" data-state="done" data-size="sm" data-orientation="horizontal" class=${cn(attachmentClass({ size: 'sm' }), 'w-full')}>
<div data-slot="attachment-media" data-variant="icon" class=${attachmentMediaClass()}>
${FileTextIcon()}
</div>
<div data-slot="attachment-content" class=${attachmentContentClass()}>
<span data-slot="attachment-title" class=${attachmentTitleClass()}>Small attachment</span>
<span data-slot="attachment-description" class=${attachmentDescriptionClass()}>PDF · 2.4 MB</span>
</div>
</div>
<div data-slot="attachment" data-state="done" data-size="xs" data-orientation="horizontal" class=${cn(attachmentClass({ size: 'xs' }), 'w-full')}>
<div data-slot="attachment-media" data-variant="icon" class=${attachmentMediaClass()}>
${FileTextIcon()}
</div>
<div data-slot="attachment-content" class=${attachmentContentClass()}>
<span data-slot="attachment-title" class=${attachmentTitleClass()}>Extra small attachment</span>
</div>
</div>
</div>
`;
}
View Code
Group
Wrap attachments in an element with attachmentGroupClass() to lay them out in a horizontally scrollable, snapping row with an edge fade.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
attachmentClass, attachmentMediaClass, attachmentContentClass, attachmentTitleClass,
attachmentDescriptionClass, attachmentActionsClass, attachmentActionClass, attachmentGroupClass,
} from '#components/ui/attachment.ts';
import { FileCodeIcon, FileTextIcon, TableIcon, XIcon } from '#lib/ui/lucide.ts';
type Item = {
name: string;
meta: string;
icon?: (cls?: string) => unknown;
src?: string;
};
const items: Item[] = [
{ name: 'briefing-notes.pdf', meta: 'PDF · 1.4 MB', icon: FileTextIcon },
{
name: 'workspace.png',
meta: 'PNG · 820 KB',
src: 'https://images.unsplash.com/photo-1497366754035-f200968a6e72?w=900&auto=format&fit=crop&q=80',
},
{ name: 'customers.csv', meta: 'CSV · 18 KB', icon: TableIcon },
{ name: 'renderer.tsx', meta: 'TSX · 12 KB', icon: FileCodeIcon },
];
export default function AttachmentGroupDemo() {
return html`
<div class="mx-auto w-full max-w-sm py-12">
<div data-slot="attachment-group" class=${cn(attachmentGroupClass(), 'w-full')}>
${items.map((item) => html`
<div data-slot="attachment" data-state="done" data-size="default" data-orientation="horizontal" class=${cn(attachmentClass(), 'w-64')}>
${item.src
? html`<div data-slot="attachment-media" data-variant="image" class=${attachmentMediaClass({ variant: 'image' })}>
<img src=${item.src} alt=${item.name}>
</div>`
: item.icon
? html`<div data-slot="attachment-media" data-variant="icon" class=${attachmentMediaClass()}>
${item.icon()}
</div>`
: ''}
<div data-slot="attachment-content" class=${attachmentContentClass()}>
<span data-slot="attachment-title" class=${attachmentTitleClass()}>${item.name}</span>
<span data-slot="attachment-description" class=${attachmentDescriptionClass()}>${item.meta}</span>
</div>
<div data-slot="attachment-actions" class=${attachmentActionsClass()}>
<button type="button" data-slot="attachment-action" data-variant="ghost" data-size="icon-xs" aria-label=${`Remove ${item.name}`} class=${cn(buttonClass({ variant: 'ghost', size: 'icon-xs' }), attachmentActionClass())}>
${XIcon()}
</button>
</div>
</div>
`)}
</div>
</div>
`;
}
View Code
Trigger
Add a trigger to make the whole card open a link or dialog. attachmentTriggerClass() fills the card behind the actions, so the actions stay clickable.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
dialogHeaderClass, dialogTitleClass, dialogDescriptionClass,
} from '#components/ui/dialog.ts';
import {
attachmentClass, attachmentMediaClass, attachmentContentClass, attachmentTitleClass,
attachmentDescriptionClass, attachmentActionsClass, attachmentActionClass, attachmentTriggerClass,
} from '#components/ui/attachment.ts';
import { CopyIcon, FileSearchIcon, XIcon } from '#lib/ui/lucide.ts';
export default function AttachmentTriggerDemo() {
return html`
<div class="mx-auto w-full max-w-sm py-12">
<ui-dialog>
<div data-slot="attachment" data-state="done" data-size="default" data-orientation="horizontal" class=${cn(attachmentClass(), 'w-full')}>
<div data-slot="attachment-media" data-variant="icon" class=${attachmentMediaClass()}>
${FileSearchIcon()}
</div>
<div data-slot="attachment-content" class=${attachmentContentClass()}>
<span data-slot="attachment-title" class=${attachmentTitleClass()}>research-summary.pdf</span>
<span data-slot="attachment-description" class=${attachmentDescriptionClass()}>Open preview dialog</span>
</div>
<div data-slot="attachment-actions" class=${attachmentActionsClass()}>
<button type="button" data-slot="attachment-action" data-variant="ghost" data-size="icon-xs" aria-label="Copy link" class=${cn(buttonClass({ variant: 'ghost', size: 'icon-xs' }), attachmentActionClass())}>
${CopyIcon()}
</button>
<button type="button" data-slot="attachment-action" data-variant="ghost" data-size="icon-xs" aria-label="Remove research-summary.pdf" class=${cn(buttonClass({ variant: 'ghost', size: 'icon-xs' }), attachmentActionClass())}>
${XIcon()}
</button>
</div>
<ui-dialog-trigger>
<button type="button" data-slot="attachment-trigger" aria-label="Preview research-summary.pdf" class=${attachmentTriggerClass()}></button>
</ui-dialog-trigger>
</div>
<ui-dialog-content class="sm:max-w-md">
<div data-slot="dialog-header" class=${dialogHeaderClass()}>
<h2 data-slot="dialog-title" class=${dialogTitleClass()}>research-summary.pdf</h2>
<p data-slot="dialog-description" class=${dialogDescriptionClass()}>
The attachment trigger fills the card and opens the dialog, while
the actions stay independently clickable above it.
</p>
</div>
</ui-dialog-content>
</ui-dialog>
</div>
`;
}
View Code
<ui-dialog>
<div data-slot="attachment" class=${attachmentClass()}>
<!-- media, content, actions -->
<ui-dialog-trigger>
<button type="button" data-slot="attachment-trigger" aria-label="Preview research-summary.pdf"
class=${attachmentTriggerClass()}></button>
</ui-dialog-trigger>
</div>
<ui-dialog-content><!-- ... --></ui-dialog-content>
</ui-dialog>
Accessibility
An action is a native <button> with the button classes, and the trigger is a real <button> or <a>. Follow the guidance below so both are operable and announced.
Label icon-only actions
An action is usually icon-only, so give each one an aria-label describing the action and its target.
<button type="button" data-slot="attachment-action" aria-label="Remove sales-dashboard.pdf"
class=${cn(buttonClass({ variant: 'ghost', size: 'icon-xs' }), attachmentActionClass())}>
${XIcon()}
</button>
Label the trigger
The trigger covers the card with no text of its own, so give it an aria-label for what activating it does.
<a
data-slot="attachment-trigger"
href=${url}
target="_blank"
rel="noreferrer"
aria-label="Open workspace.png"
class=${attachmentTriggerClass()}
></a>
The trigger sits behind the actions in the stacking order, so an action and the trigger never trap each other. Both remain separately focusable and clickable.
Keyboard scrolling
A group 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 the description so the state is not conveyed by color alone.
API Reference
Every part is a helper that returns classes for a plain element. Set the part's data-slot, and the data-state, data-size, data-orientation and data-variant attributes that match the options you pass, since the styles key on them.
attachmentClass
The root attachment container, on data-slot="attachment". attachmentVariants() is an alias of attachmentClass() that also merges a className.
attachmentMediaClass
The media slot for an icon or image preview, on data-slot="attachment-media". attachmentMediaVariants() is an alias of attachmentMediaClass() that also merges a className.
attachmentContentClass
Wraps the title and description, on data-slot="attachment-content". It takes no options.
attachmentTitleClass
The attachment name, on data-slot="attachment-title". Shimmers while the attachment is uploading or processing. It takes no options.
attachmentDescriptionClass
Secondary metadata such as the file type, size, or upload status, on data-slot="attachment-description". It takes no options.
attachmentActionsClass
A container for one or more actions, aligned to the end of the attachment, on data-slot="attachment-actions". It takes no options.
attachmentActionClass
An action button, on data-slot="attachment-action". Merge it with buttonClass({ variant: 'ghost', size: 'icon-xs' }) on a native <button>; any other Button variant and size work too.
attachmentTriggerClass
A full-card overlay that activates the attachment, on data-slot="attachment-trigger". Put it on a <button> (inside a <ui-dialog-trigger> to open a dialog) or on an <a> to open a link. It takes no options.
attachmentGroupClass
Lays out attachments in a horizontally scrollable, snapping row, on data-slot="attachment-group". It takes no options.