Attachment

UI components for attaching and viewing files in messages.

Send a message...

Note: These components provide the UI for attachments, but you also need to configure attachment adapters in your runtime to handle file uploads and processing. See the Attachments Guide for complete setup instructions.

Getting Started

Add attachment

npx shadcn@latest add @assistant-ui/attachment

The @assistant-uinamespace resolves the Radix or Base UI flavor from your project's style through the style-aware registry entry in components.json. Without that entry, add by direct URL instead:

npx shadcn@latest add https://r.assistant-ui.com/base/attachment.json

This adds a /components/assistant-ui/attachment.tsx file to your project, which you can adjust as needed.

Use in your application

/components/assistant-ui/thread.tsx
import {
  ComposerAttachments,
  ComposerAddAttachment,
} from "@/components/assistant-ui/attachment";

const Composer: FC = () => {
  return (
    <ComposerPrimitive.Root className="...">
      <ComposerAttachments />
      <ComposerAddAttachment />

      <ComposerPrimitive.Input
        autoFocus
        placeholder="Write a message..."
        rows={1}
        className="..."
      />
      <ComposerAction />
    </ComposerPrimitive.Root>
  );
};
/components/assistant-ui/thread.tsx
import { UserMessageAttachments } from "@/components/assistant-ui/attachment";

const UserMessage: FC = () => {
  return (
    <MessagePrimitive.Root className="...">
      <UserActionBar />

      <UserMessageAttachments />

      <div className="...">
        <MessagePrimitive.Parts />
      </div>

      <BranchPicker className="..." />
    </MessagePrimitive.Root>
  );
};

API Reference

Composer Attachments

ComposerPrimitive.Attachments

Renders all attachments in the composer.

ComposerPrimitiveAttachmentsProps
components ?: AttachmentComponents

Components to render for different attachment types.

Image ?: ComponentType

Component for image attachments.

Document ?: ComponentType

Component for document attachments (PDF, etc.).

File ?: ComponentType

Component for generic file attachments.

Attachment ?: ComponentType

Fallback component for all attachment types.

ComposerPrimitive.AddAttachment

A button that opens the file picker to add attachments.

ComposerPrimitiveAddAttachmentProps
multiple : boolean = true

Allow selecting multiple files at once.

asChild : boolean = false

Merge props with child element instead of rendering a wrapper button.

This primitive renders a <button> element unless asChild is set.

Message Attachments

MessagePrimitive.Attachments

Renders all attachments in a user message.

MessagePrimitiveAttachmentsProps
components ?: AttachmentComponents

Components to render for different attachment types (same as ComposerPrimitive.Attachments).

Attachment Primitives

AttachmentPrimitive.Root

Container for a single attachment.

AttachmentPrimitiveRootProps
asChild : boolean = false

Merge props with child element instead of rendering a wrapper div.

AttachmentPrimitive.Name

Renders the attachment's file name.

AttachmentPrimitive.Remove

A button to remove the attachment from the composer.

AttachmentPrimitiveRemoveProps
asChild : boolean = false

Merge props with child element instead of rendering a wrapper button.

Attachment Types

Attachments have the following structure:

type Attachment = {
  id: string;
  type: "image" | "document" | "file" | (string & {});
  name: string;
  contentType?: string;
  file?: File;
  status:
    | { type: "running" | "requires-action" | "incomplete"; progress?: number }
    | { type: "complete" };
};

The type field accepts custom strings (e.g. "data-workflow") beyond the built-in types. When an unknown type is encountered, the generic Attachment component is used as a fallback. The contentType field is optional — it can be omitted for non-file attachments where a MIME type is not meaningful.

  • Thread - Main chat interface that displays attachments
  • Attachments Guide - Complete setup instructions for attachment adapters