For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Attachment

Displays file attachments with state, size, media, and overlay actions.

Web
Frakment
Workspace
workspace.avifAVIF · 42 KB
Desk
desk-reference.avifAVIF · 14 KB
Office
office-reference.avifAVIF · 38 KB
sales-dashboard.pdfUploading · 64%
message-renderer.tsxTypeScript · 12 KB
attachment.tsx
"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

Usage

attachment.tsx
import {
  Attachment,
  AttachmentContent,
  AttachmentDescription,
  AttachmentMedia,
  AttachmentTitle,
} from "@/components/ui/attachment";
tsx
<Attachment>
  <AttachmentMedia>
    <FileTextIcon />
  </AttachmentMedia>
  <AttachmentContent>
    <AttachmentTitle>report.pdf</AttachmentTitle>
    <AttachmentDescription>PDF · 2.4 MB</AttachmentDescription>
  </AttachmentContent>
</Attachment>

Composition

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

Examples

States

Control the visual state with the state prop. States affect color, shimmer, and action visibility.

selected-file.pdfReady to upload
design-system.zipUploading · 64%
market-research.pdfProcessing document
financial-model.xlsxUpload failed. Try again.
uploaded-report.pdfUploaded · 1.8 MB
attachment-states.tsx
"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.

attachment-image.tsx
"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.

briefing-notes.pdfPDF · 1.4 MB
workspace.avif
workspace.avifAVIF · 39 KB
customers.csvCSV · 18 KB
renderer.tsxTSX · 12 KB
attachment-group.tsx
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.

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

Default attachmentPDF · 2.4 MB
Small attachmentPDF · 2.4 MB
Extra small attachment
attachment-sizes.tsx
"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.

research-summary.pdfOpen preview dialog
attachment-trigger.tsx
"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.tsx
<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

brief.pdfUploading · 42%
notes.mdMarkdown · 4 KB
renderer.tsxTypeScript · 12 KB
attachment-upload-queue.tsx
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

report.pdfPDF · 2.4 MB
script.tsTypeScript · 8 KB
attachment-group-context.tsx
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

PropTypeDefaultDescription
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

PropTypeDefaultDescription
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

PropTypeDefaultDescription
asReact.ElementType—Render as a different element or component. Accepts HTML tag names or React components. Defaults to button.
aria-labelstring—Required. Describes the target action (e.g. Preview report.pdf).

Data Attributes

AttributeValues
data-slotattachment, attachment-media, attachment-content, attachment-title, attachment-description, attachment-actions, attachment-action, attachment-trigger, attachment-group
data-stateidle | uploading | processing | error | done
data-sizedefault | sm | xs
data-orientationhorizontal | vertical
data-varianticon | image

Accessibility

  • AttachmentTrigger is an absolute overlay. Give it an aria-label describing the target action, such as "Preview report.pdf".
  • AttachmentAction buttons are icon-only. Every action must have an aria-label so screen readers can announce its intent.
  • Do not attach click handlers to the card itself. Use AttachmentTrigger with as (or as DialogTrigger with as={AttachmentTrigger}) so the click target is a real anchor or button.
  • Pair color with icon or text. The error state uses file-warning and 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 state for 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 AttachmentGroup for lists. It normalizes spacing and snap behavior between cards.
  • Wrap with as for links. A plain overlay without as is a button with no semantic role; pass as="a" for anchors or wrap in DialogTrigger with as={AttachmentTrigger}.
  • Message — bubble attachments
  • Spinner — uploading state