---
title: Message
description: Composable chat message layout with markdown body, optional avatar, actions, and attachments
---

import MessageDefault from "@/components/nexus-ui/examples/message/default";
import MessageWithActions from "@/components/nexus-ui/examples/message/with-actions";
import MessageWithAvatar from "@/components/nexus-ui/examples/message/with-avatar";
import MessageWithAttachments from "@/components/nexus-ui/examples/message/with-attachments";
import MessageRichText from "@/components/nexus-ui/examples/message/rich-text";

Composable **user** and **assistant** chat turns via **`Message`**, **`MessageContent`**, **`MessageMarkdown`** ([Streamdown](https://github.com/vercel/streamdown)), **`MessageAvatar`**, **`MessageActions`**, and **[Attachments](/docs/components/attachments)**.

<DemoWithCode src="components/nexus-ui/examples/message/default.tsx">
  <MessageDefault />
</DemoWithCode>

## Installation

<Tabs items={["CLI", "Manual"]} framed={false}>
<Tab value="CLI">
<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
<Tab value="npm">
```bash
npx shadcn@latest add @nexus-ui/message
```
</Tab>
<Tab value="pnpm">
```bash
pnpm dlx shadcn@latest add @nexus-ui/message
```
</Tab>
<Tab value="yarn">
```bash
yarn dlx shadcn@latest add @nexus-ui/message
```
</Tab>
<Tab value="bun">
```bash
bunx shadcn@latest add @nexus-ui/message
```
</Tab>
</Tabs>
</Tab>
<Tab value="Manual">
<Steps>
<Step>
<h3>Copy and paste the following code into your project.</h3>

<ComponentSource src="registry/new-york/message/message.tsx" title="components/nexus-ui/message.tsx" />

<ComponentSource src="registry/new-york/message/codeblock.tsx" title="components/nexus-ui/codeblock.tsx" />
</Step>
<Step>
<h3>Update the import paths to match your project setup.</h3>
</Step>
</Steps>
</Tab>
</Tabs>

## Usage

```tsx keepBackground
import {
  Message,
  MessageStack,
  MessageContent,
  MessageMarkdown,
  MessageActions,
  MessageActionGroup,
  MessageAction,
  MessageAvatar,
} from "@/components/nexus-ui/message";
```

```tsx keepBackground
<Message from="user">
  <MessageStack>
    <MessageContent>
      <MessageMarkdown>Hello</MessageMarkdown>
    </MessageContent>
  </MessageStack>
  <MessageAvatar src="/avatar.png" alt="You" fallback="Y" />
</Message>
```

## Examples

### With Actions

Use **`MessageActions`** and **`MessageActionGroup`** for a row of controls. **`MessageAction`** is a thin **Slot** for individual action buttons.

<DemoWithCode src="components/nexus-ui/examples/message/with-actions.tsx">
  <MessageWithActions />
</DemoWithCode>

### With Avatar

**`MessageAvatar`** composes shadcn **Avatar** / **AvatarImage** / **AvatarFallback** — pass **`src`**, **`alt`**, and optional **`fallback`** (and **`delayMs`** if needed). Place the avatar **after** **`MessageStack`** for **`from="user"`**, and **before** **`MessageStack`** for **`from="assistant"`**.

<DemoWithCode src="components/nexus-ui/examples/message/with-avatar.tsx">
  <MessageWithAvatar />
</DemoWithCode>

### With Attachments

Render **`AttachmentList`** / **`Attachment`** inside **`MessageStack`** above **`MessageContent`**. Use **`readOnly`** on **`Attachment`** when showing files that were already sent (no remove control or progress). See **[Attachments](/docs/components/attachments)** for **`AttachmentMeta`** and variants.

<DemoWithCode src="components/nexus-ui/examples/message/with-attachments.tsx">
  <MessageWithAttachments />
</DemoWithCode>

### Rich Text (Markdown)

**`MessageMarkdown`** renders markdown with **Streamdown** and shared prose-style classes. Pass a string as **`children`** (or a template literal) for headings, lists, code blocks, and links.

<DemoWithCode
  previewClassName="h-[600px] justify-start overflow-y-auto"
  src="components/nexus-ui/examples/message/rich-text.tsx"
>
  <MessageRichText />
</DemoWithCode>

## Message and Streamdown

### How **MessageMarkdown** uses Streamdown

It is a thin wrapper around **[Streamdown](https://github.com/vercel/streamdown)** with the same component props, so you can pass **`children`**, **`className`**, and other **`Streamdown`** options as needed.

Nexus applies shared **prose-style** **`className`** tokens for headings, body text, links, lists, and inline code. **Shiki** highlights fenced code with **`github-light`** and **`github-dark`**.

**Plugins** from **`@streamdown/code`**, **`@streamdown/math`**, **`@streamdown/mermaid`**, and **`@streamdown/cjk`** enable code blocks, math, diagrams, and CJK-friendly typography. A few **MDX components** are overridden—especially **tables** and **codeblocks**.

Streamdown parses markdown into HTML that relies on utility classes shipped inside **`streamdown`** and those plugin packages. That model works well for **streaming** assistant output so you do not hand-build the markup.

### Fenced Code 

**`MessageMarkdown`** uses **`CodeBlock`** for **`components.code`** (`@/components/nexus-ui/codeblock`). **`@streamdown/code`** still handles highlighting—you are only swapping the **UI**.

Use **`CodeBlock`** **`showTitleRow`** to show or hide the fenced-block title row (pass it on your **`components.code`** renderer). Turn line gutters on or off with Streamdown **`lineNumbers`**, which **`MessageMarkdown`** forwards like any other Streamdown prop.

**`@nexus-ui/message`** ships **`message.tsx`** and **`codeblock.tsx`** in one install—there is no separate codeblock package.

### Tailwind **@source** after install

Installing **Message** with the **shadcn CLI** should merge **Tailwind `@source`** lines into the CSS file from **`components.json`** so those classes are **not purged**. With a **manual** install, that merge does not run by default.

After either path, **open your global CSS** and **confirm** the **`@source`** entries for **`streamdown`** and **`@streamdown/*`** are present, and that **`../node_modules`** still resolves to the project root from that file’s folder. If anything is missing or the depth is wrong, markdown can look unstyled or code and diagrams can break.

## Vercel AI SDK Integration

Render [`useChat`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) messages with **Message** by reading each **[`UIMessage`](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message)** **`parts`** array. Join **`text`** parts for **MessageMarkdown** (streaming updates apply as the SDK appends or grows **`TextUIPart`** content).

See [Prompt Input](/docs/components/prompt-input#vercel-ai-sdk-integration) for a minimal **`POST /api/chat`** route with **`streamText`** and **`toUIMessageStreamResponse`**. For user turns that include uploads, map **`file`** parts to **[Attachments](/docs/components/attachments)** (or your own preview) in addition to text—**[Attachments](/docs/components/attachments#vercel-ai-sdk-integration)** covers **`sendMessage`** with **`files`**.

<Steps>
<Step>
<h3>Install the AI SDK</h3>

```bash
npm install ai @ai-sdk/react @ai-sdk/openai
```

</Step>
<Step>
<h3>Create your chat API route</h3>

Use the same handler as in the Prompt Input docs: **`messages: await convertToModelMessages(messages)`** and **`return result.toUIMessageStreamResponse()`**.

</Step>
<Step>
<h3>Map `messages` to Message</h3>

Use **`isTextUIPart`** from **`ai`** so you only aggregate **`type: "text"`** segments. Skip **`system`** turns unless you surface them deliberately. Assistant messages can also include **reasoning**, **tool**, **source**, and other part types—extend this loop when you need those in the UI.

```tsx
"use client";

import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport, isTextUIPart, type UIMessage } from "ai";
import {
  Message,
  MessageStack,
  MessageContent,
  MessageMarkdown,
} from "@/components/nexus-ui/message";

function textFromMessage(message: UIMessage) {
  return message.parts.filter(isTextUIPart).map((p) => p.text).join("");
}

export default function ChatThread() {
  const { messages } = useChat({
    transport: new DefaultChatTransport({ api: "/api/chat" }),
  });

  return (
    <div className="flex flex-col gap-4">
      {messages
        .filter((m) => m.role !== "system")
        .map((m) => (
          <Message key={m.id} from={m.role === "user" ? "user" : "assistant"}>
            <MessageStack>
              <MessageContent>
                <MessageMarkdown>{textFromMessage(m)}</MessageMarkdown>
              </MessageContent>
            </MessageStack>
          </Message>
        ))}
    </div>
  );
}
```

</Step>
</Steps>

## API Reference

### Message

Root of one chat turn: row for stack, avatar, and siblings; **`from`** sets alignment and is provided in context to **`MessageStack`**, **`MessageContent`**, and **`MessageActions`**.

<TypeTable
  type={{
    from: {
      type: '"user" | "assistant"',
      description:
        "User vs assistant; alignment on Message and nested layout/styles via context.",
    },
    "aria-label": {
      type: "string",
      description:
        "Accessible name for the turn. Defaults to User message / Assistant message unless aria-labelledby is set.",
    },
    "aria-labelledby": {
      type: "string",
      description:
        "Optional id(s) of visible labels; when set, a default aria-label is not applied.",
    },
    className: {
      type: "string",
      description: "Additional CSS classes to apply to the message row.",
    },
  }}
/>

### MessageStack

Stacks bubble, attachments, and actions in a column; cross-axis alignment follows **`from`** on **`Message`** (user vs assistant).

<TypeTable
  type={{
    className: {
      type: "string",
      description: "Additional CSS classes to apply to the stack container.",
    },
  }}
/>

### MessageContent

Wraps the message body (e.g. markdown inside). **User** turns get a filled bubble; **assistant** turns stay visually light on the thread—both follow **`from`** on **`Message`**.

<TypeTable
  type={{
    className: {
      type: "string",
      description: "Additional CSS classes to apply to the bubble.",
    },
  }}
/>

### MessageMarkdown

Renders **markdown** with **[Streamdown](https://github.com/vercel/streamdown)**. Props are forwarded to **`Streamdown`**; values you pass replace the same keys on the underlying component (e.g. a new **`plugins`** object replaces the default bundle).

Commonly used options:

<TypeTable
  type={{
    children: {
      type: "string",
      description: "Markdown source to render.",
    },
    className: {
      type: "string",
      description:
        "Additional CSS classes to apply to the Streamdown root element.",
    },
    mode: {
      type: '"streaming" | "static"',
      default: '"streaming"',
      description:
        "`streaming` for live token flow; `static` for finished content.",
    },
    isAnimating: {
      type: "boolean",
      default: "false",
      description:
        "Whether content is actively streaming (e.g. disables some controls).",
    },
    parseIncompleteMarkdown: {
      type: "boolean",
      default: "true",
      description:
        "Use the remend preprocessor for unfinished markdown while streaming.",
    },
    plugins: {
      type: "PluginConfig",
      description:
        "Math, Mermaid, Shiki, and CJK plugins. Replaces MessageMarkdown defaults when set.",
    },
    controls: {
      type: "ControlsConfig | boolean",
      description:
        "Show or hide table/code/Mermaid control buttons. Replaces MessageMarkdown defaults when set.",
    },
    components: {
      type: "Components",
      description:
        "Map markdown nodes to custom React elements. Replaces MessageMarkdown defaults when set.",
    },
    shikiTheme: {
      type: "[ThemeInput, ThemeInput]",
      default: "['github-light', 'github-dark']",
      description:
        "Light and dark syntax-highlighting themes for fenced code blocks.",
    },
  }}
/>

For **`remend`**, **`remarkPlugins`**, **`rehypePlugins`**, **`linkSafety`**, **`animated`**, **`caret`**, and the full prop list, see the [Streamdown configuration docs](https://streamdown.ai/docs/configuration).


### MessageActions

A flex container for action buttons. Default **`justify-end`** (user) or **`justify-start`** (assistant); override with **`className`** (e.g. **`justify-between`**) for multiple groups.

<TypeTable
  type={{
    className: {
      type: "string",
      description:
        "Additional CSS classes to apply to the actions container.",
    },
  }}
/>

### MessageActionGroup

Groups related action buttons together with a horizontal layout.

<TypeTable
  type={{
    className: {
      type: "string",
      description:
        "Additional CSS classes to apply to the group container.",
    },
  }}
/>

### MessageAction

A wrapper for individual action buttons. Supports polymorphism via `asChild`.

<TypeTable
  type={{
    asChild: {
      type: "boolean",
      default: "false",
      description: "Render as the child element instead of a div.",
    },
    className: {
      type: "string",
      description:
        "Additional CSS classes to apply to the action.",
    },
  }}
/>

### MessageAvatar

**shadcn** [**Avatar**](https://ui.shadcn.com/docs/components/avatar) with **`src`** / **`alt`** / optional **`fallback`**. Sibling to **`MessageStack`** in **`Message`**: after the stack for **user**, before for **assistant**.

<TypeTable
  type={{
    src: {
      type: "string",
      description: "Image URL passed to AvatarImage.",
    },
    alt: {
      type: "string",
      default: '""',
      description: "AvatarImage alt text.",
    },
    fallback: {
      type: "React.ReactNode",
      description:
        "Optional. Shown inside AvatarFallback while loading or if the image errors.",
    },
    delayMs: {
      type: "number",
      description:
        "Optional. Passed to AvatarFallback (Radix delay before showing fallback).",
    },
    size: {
      type: '"default" | "sm" | "lg"',
      description: "Optional. shadcn Avatar size.",
    },
    className: {
      type: "string",
      description:
        "Additional CSS classes to apply to the Avatar root.",
    },
  }}
/>