# Attachment

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

Source: https://webjs.dev/ui/docs/components/attachment

```ts
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>
  `;
}
```

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

```bash
npx @webjsdev/ui add attachment
```

### Copy and paste the following code into your project.

````ts title="components/ui/attachment.ts"
/**
 * 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

```ts
import {
  attachmentClass,
  attachmentMediaClass,
  attachmentContentClass,
  attachmentTitleClass,
  attachmentDescriptionClass,
  attachmentActionsClass,
  attachmentActionClass,
} from '#components/ui/attachment.ts';
```

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

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

```text
AttachmentGroup
├── Attachment
└── Attachment
```

## Features

- Icon and image media through `attachmentMediaClass()`
- 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 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.

```ts
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>
  `;
}
```

## States

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

```ts
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>
  `;
}
```

## Sizes

Use the `size` option (with a matching `data-size`) to switch between `default`, `sm`, and `xs`.

```ts
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>
  `;
}
```

## Group

Wrap attachments in an element with `attachmentGroupClass()` to lay them out in a horizontally scrollable, snapping row with an edge fade.

```ts
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>
  `;
}
```

## 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.

```ts
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>
  `;
}
```

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

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

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

| Option or attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `data-state` | `"idle" \| "uploading" \| "processing" \| "error" \| "done"` | `"done"` | The upload state. Drives styling and the shimmer. |
| `size` | `"default" \| "sm" \| "xs"` | `"default"` | The attachment size. Mirror it in `data-size`. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Lay the media beside or above the content. Mirror it in `data-orientation`. |

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

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"icon" \| "image"` | `"icon"` | Whether the media holds an icon or an `<img>`. Mirror it in `data-variant`. |

### 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](https://webjs.dev/ui/docs/components/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.
