# Attachment
URL: /docs/ui/attachment

UI components for attaching and viewing files in messages.

<AttachmentSample />

<Callout type="info">
  **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](/docs/guides/attachments) for complete
  setup instructions.
</Callout>

Getting Started \[#getting-started]

<Steps>
  <Step>
    Add `attachment` \[#add-attachment]

    <InstallCommand shadcn="[&#x22;attachment&#x22;]" />

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

  <Step>
    Use in your application \[#use-in-your-application]

    ```tsx title="/components/assistant-ui/thread.tsx" {1-4,9-10}
    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>
      );
    };
    ```

    ```tsx title="/components/assistant-ui/thread.tsx" {1,8}
    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>
      );
    };
    ```
  </Step>
</Steps>

API Reference \[#api-reference]

Composer Attachments \[#composer-attachments]

ComposerPrimitive.Attachments \[#composerprimitiveattachments]

Renders all attachments in the composer.

<ParametersTable
  type="ComposerPrimitiveAttachmentsProps"
  parameters="[
{
name: &#x22;components&#x22;,
type: &#x22;AttachmentComponents&#x22;,
description: &#x22;Components to render for different attachment types.&#x22;,
children: [
{
type: &#x22;AttachmentComponents&#x22;,
parameters: [
{
name: &#x22;Image&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;Component for image attachments.&#x22;,
},
{
name: &#x22;Document&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;Component for document attachments (PDF, etc.).&#x22;,
},
{
name: &#x22;File&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;Component for generic file attachments.&#x22;,
},
{
name: &#x22;Attachment&#x22;,
type: &#x22;ComponentType&#x22;,
description: &#x22;Fallback component for all attachment types.&#x22;,
},
],
},
],
},
]"
/>

ComposerPrimitive.AddAttachment \[#composerprimitiveaddattachment]

A button that opens the file picker to add attachments.

<ParametersTable
  type="ComposerPrimitiveAddAttachmentProps"
  parameters="[
{
name: &#x22;multiple&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;true&#x22;,
description: &#x22;Allow selecting multiple files at once.&#x22;,
},
{
name: &#x22;asChild&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;false&#x22;,
description: &#x22;Merge props with child element instead of rendering a wrapper button.&#x22;,
},
]"
/>

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

Message Attachments \[#message-attachments]

MessagePrimitive.Attachments \[#messageprimitiveattachments]

Renders all attachments in a user message.

<ParametersTable
  type="MessagePrimitiveAttachmentsProps"
  parameters="[
{
name: &#x22;components&#x22;,
type: &#x22;AttachmentComponents&#x22;,
description: &#x22;Components to render for different attachment types (same as ComposerPrimitive.Attachments).&#x22;,
},
]"
/>

Attachment Primitives \[#attachment-primitives]

AttachmentPrimitive.Root \[#attachmentprimitiveroot]

Container for a single attachment.

<ParametersTable
  type="AttachmentPrimitiveRootProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;false&#x22;,
description: &#x22;Merge props with child element instead of rendering a wrapper div.&#x22;,
},
]"
/>

AttachmentPrimitive.Name \[#attachmentprimitivename]

Renders the attachment's file name.

AttachmentPrimitive.Remove \[#attachmentprimitiveremove]

A button to remove the attachment from the composer.

<ParametersTable
  type="AttachmentPrimitiveRemoveProps"
  parameters="[
{
name: &#x22;asChild&#x22;,
type: &#x22;boolean&#x22;,
default: &#x22;false&#x22;,
description: &#x22;Merge props with child element instead of rendering a wrapper button.&#x22;,
},
]"
/>

Attachment Types \[#attachment-types]

Attachments have the following structure:

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

Related Components \[#related-components]

* [Thread](/docs/ui/thread) - Main chat interface that displays attachments
* [Attachments Guide](/docs/guides/attachments) - Complete setup instructions for attachment adapters