Attachment

Thread already renders every piece below by default; use these directly if you're composing your own layout instead of Thread.

import { ComposerPrimitive } from "@assistant-ui/react";
import {
  ComposerAddAttachment,
  ComposerAttachments,
} from "@/components/assistant-ui/elements/attachment.aui";

function Composer() {
  return (
    <ComposerPrimitive.Root>
      <ComposerPrimitive.AttachmentDropzone>
        <ComposerAttachments />
        <ComposerPrimitive.Input placeholder="Send a message..." />
        <ComposerAddAttachment />
      </ComposerPrimitive.AttachmentDropzone>
    </ComposerPrimitive.Root>
  );
}

import { MessagePrimitive } from "@assistant-ui/react";
import { UserMessageAttachments } from "@/components/assistant-ui/elements/attachment.aui";

function UserMessage() {
  return (
    <MessagePrimitive.Root>
      <UserMessageAttachments />
      <MessagePrimitive.Parts />
    </MessagePrimitive.Root>
  );
}

<div> {/* AttachmentPrimitive.Root */}
  <button aria-label="Image attachment" /* or "Document attachment" / "File attachment", plus ", uploading" / ", upload failed" */>
    {/* thumbnail: the image itself, or a file icon fallback */}
    {/* uploading: a blurred spinner overlay */}
    {/* error: a blurred alert overlay */}
  </button>
  <button aria-label="Remove file">{/* composer only */}</button>
</div>

The remove button and the upload/error overlays only render on a composer attachment; a message attachment shows the tile alone. A lone image attachment on a message renders larger than the rest. Clicking an image tile whose source resolves opens a fullscreen preview dialog; any other kind of tile, or an image with no resolvable source yet, renders the click target with no dialog behavior at all.

Composer vs. message attachments

Both exports render the same tile; only the source differs. aui.attachment.source is "composer" for a staged attachment and "message" for one already sent, and that's exactly what decides whether the remove button and drag-in animation appear.

<ComposerAttachments />       {/* ComposerPrimitive.Attachments, source: "composer" */}
<UserMessageAttachments />    {/* MessagePrimitive.Attachments, source: "message" */}

Reading the resolved preview source

useAttachmentSrc() resolves an image attachment's displayable URL: an object URL for a file still in memory, or the first image content part once the attachment has uploaded. Anything that isn't an image resolves to undefined, which is exactly the signal a custom preview uses to fall back to an icon.

import { useAttachmentSrc } from "@/hooks/use-attachment-src";

function CustomThumb() {
  const src = useAttachmentSrc();
  if (!src) return <FileIcon />;
  return <img src={src} alt="" />;
}

Add-attachment picker

ComposerAddAttachment opens a native file picker scoped to the composer's own attachmentAccept, and supports selecting more than one file at once. It renders nothing while the composer isn't editable (for example, while a run is streaming).

<ComposerAddAttachment />

Kit parts

Primitives composed

Attachment state

Wire it by mapping a user message's attachments into items; like UserMessageAttachments above, this only makes sense inside a user message. s.message.attachments is the store's own array and every entry is already complete (an upload still in progress lives in the composer's own attachments instead), so selecting it directly is cheap; deriving items still needs useMemo, since mapping to a fresh array on every call would re-render the list on every store update.

"use client";

import { useMemo } from "react";
import { useAuiState } from "@assistant-ui/react";
import {
  MessageAttachments,
  type MessageAttachmentItem,
} from "@/components/assistant-ui/elements/message-attachment";

function UserReceivedFiles() {
  const attachments = useAuiState((s) => s.message.attachments);
  const items = useMemo<MessageAttachmentItem[]>(
    () =>
      attachments.map((a) => ({
        id: a.id,
        name: a.name,
        size: formatFileSize(a),
        kind: a.type === "image" || a.type === "document" ? a.type : "file",
      })),
    [attachments],
  );

  if (items.length === 0) return null;
  return (
    <MessageAttachments attachments={items} onOpen={(id) => openViewer(id)} />
  );
}

The runtime carries id, type, name, and contentType, but no formatted size string or page count, so formatFileSize above is yours to write; a provider-defined custom type collapses to "file", since kind only accepts the three shown.