Skip to content
WebJs
Menu

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

Workspace
workspace.png PNG · 820 KB
Desk
desk-reference.jpg JPG · 1.1 MB
Office
office-reference.jpg JPG · 940 KB
sales-dashboard.pdf Uploading · 64%
message-renderer.tsx TypeScript · 12 KB
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

pnpm dlx @webjsdev/ui add attachment

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

Workspace
workspace.png PNG · 820 KB
Desk
desk-reference.jpg JPG · 1.1 MB
Office
office-reference.jpg JPG · 940 KB
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.

selected-file.pdf Ready to upload
design-system.zip Uploading · 64%
market-research.pdf Processing document
financial-model.xlsx Upload failed. Try again.
uploaded-report.pdf Uploaded · 1.8 MB
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.

Default attachment PDF · 2.4 MB
Small attachment PDF · 2.4 MB
Extra small attachment
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.

briefing-notes.pdf PDF · 1.4 MB
workspace.png
workspace.png PNG · 820 KB
customers.csv CSV · 18 KB
renderer.tsx TSX · 12 KB
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.

research-summary.pdf Open preview dialog

research-summary.pdf

The attachment trigger fills the card and opens the dialog, while the actions stay independently clickable above it.

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.

Option or attributeTypeDefaultDescription
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.

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