# Message

Chat primitives for message layout, bubbles, scroll behavior, and streamed reply animations.

> For the complete documentation index, see [llms.txt](/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](/.well-known/agent-skills/site-skill.md).

<DocsBaseSwitcher base="web" component="message" />

<ComponentPreview name="message" title="message.tsx" previewClassName="h-auto py-8">
<MessageDemo />
</ComponentPreview>

Message ships every primitive a chat UI needs. Layout primitives (`Message`, `MessageGroup`) handle alignment and avatar placement. `Bubble` provides the rounded visual box with variant colors. `MessageScroller` anchors the viewport, follows streamed replies, and restores position on refresh. `MessageAnimated` fades in an incoming `UIMessage` with one line.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add message
```
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>

```bash
npm install class-variance-authority lucide-react
```

<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="message" title="components/ui/message.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx title="message.tsx"
import { Bubble, BubbleContent, Message, MessageAvatar, MessageContent, MessageGroup } from "@/components/ui/message";
```

```tsx
<MessageGroup>
  <Message align="start">
    <MessageAvatar>AI</MessageAvatar>
    <MessageContent>
      <Bubble variant="muted">
        <BubbleContent>Hello from the assistant.</BubbleContent>
      </Bubble>
    </MessageContent>
  </Message>
  <Message align="end">
    <MessageContent>
      <Bubble variant="default">
        <BubbleContent>Hi! How can I help?</BubbleContent>
      </Bubble>
    </MessageContent>
  </Message>
</MessageGroup>
```

## Anatomy [#anatomy]

```tsx
<MessageScrollerProvider>
  <MessageScroller>
    <MessageScrollerViewport>
      <MessageScrollerContent>
        <MessageScrollerItem messageId="1">
          <Message align="start">
            <MessageAvatar />
            <MessageContent>
              <MessageHeader />
              <Bubble>
                <BubbleContent />
                <BubbleReactions />
              </Bubble>
              <MessageFooter />
            </MessageContent>
          </Message>
        </MessageScrollerItem>
      </MessageScrollerContent>
    </MessageScrollerViewport>
    <MessageScrollerButton direction="end" />
  </MessageScroller>
</MessageScrollerProvider>
```

**Scroll container**

- **MessageScrollerProvider** - owns scroll state, item registry, visibility, and reduced-motion awareness
- **MessageScroller** - relative container with `overflow-hidden`
- **MessageScrollerViewport** - scrollable area; pass `preserveScrollOnPrepend` to keep position when prepending
- **MessageScrollerContent** - content wrapper that expands as messages arrive
- **MessageScrollerItem** - one message; pass `messageId` for anchors and `scrollAnchor` for turn anchoring
- **MessageScrollerButton** - scroll-to-end/start button; `direction="end"` (default) or `"start"`

**Message layout**

- **MessageGroup** - vertical stack of messages
- **Message** - one row; `align="start" | "end"` for side
- **MessageAvatar** - avatar slot; auto-positions when a footer is present
- **MessageContent** - content column between avatar and bubble
- **MessageHeader** - small text above the bubble (name, timestamp)
- **MessageFooter** - small text below the bubble (actions, timestamp)

**Bubble**

- **BubbleGroup** - vertical stack of bubbles inside a Message
- **Bubble** - rounded visual box; `variant` + `align`
- **BubbleContent** - inner text box; accepts `as` for anchor or router link
- **BubbleReactions** - absolute-positioned reaction strip; `align="start" | "end"`, `side="top" | "bottom"`

**Animated**

- **MessageAnimated** - reads a `UIMessage`, extracts text parts, fades the bubble in on mount

## Examples [#examples]

### With avatar [#with-avatar]

Wrap `<Avatar>` inside `MessageAvatar` to show identity next to the bubble.

<ComponentPreview name="message-avatar-demo" title="message-avatar-demo.tsx" src="examples/message-avatar-demo.tsx" previewClassName="h-auto py-6">
<lE />
</ComponentPreview>

### Message group [#message-group]

`MessageGroup` stacks consecutive messages from the same speaker with a shared avatar position.

<ComponentPreview name="message-group-demo" title="message-group-demo.tsx" src="examples/message-group-demo.tsx" previewClassName="h-auto py-6">
<lb />
</ComponentPreview>

### Header and footer [#header-and-footer]

`MessageHeader` labels the sender above the bubble. `MessageFooter` carries status, actions, or timestamps below.

<ComponentPreview name="message-header-footer-demo" title="message-header-footer-demo.tsx" src="examples/message-header-footer-demo.tsx" previewClassName="h-auto py-6">
<lF />
</ComponentPreview>

### Message actions [#message-actions]

Put copy, like, dislike, and retry buttons in `MessageFooter`. Error states use the destructive text token.

<ComponentPreview name="message-actions-demo" title="message-actions-demo.tsx" src="examples/message-actions-demo.tsx" previewClassName="h-auto py-6">
<MessageActionsDemo />
</ComponentPreview>

### Attachments [#attachments]

`Attachment` renders media or files inside a message. Vertical for images, horizontal for files with title, description, and actions.

<ComponentPreview name="message-attachment-demo" title="message-attachment-demo.tsx" src="examples/message-attachment-demo.tsx" previewClassName="h-auto py-6">
<ly />
</ComponentPreview>

### Bubble variants [#bubble-variants]

`Bubble` supports seven variants: `default`, `secondary`, `destructive`, `outline`, `ghost`, `muted`, and `tinted`.

<ComponentPreview name="bubble-variants-demo" title="bubble-variants-demo.tsx" src="examples/bubble-variants-demo.tsx" previewClassName="h-auto py-8">
<lg />
</ComponentPreview>

### Bubble alignment [#bubble-alignment]

`align="end"` anchors a bubble to the right; the default `align="start"` sits left.

<ComponentPreview name="bubble-alignment-demo" title="bubble-alignment-demo.tsx" src="examples/bubble-alignment-demo.tsx" previewClassName="h-auto py-6">
<l />
</ComponentPreview>

### Bubble group [#bubble-group]

`BubbleGroup` stacks consecutive bubbles from the same speaker with consistent alignment.

<ComponentPreview name="bubble-group-demo" title="bubble-group-demo.tsx" src="examples/bubble-group-demo.tsx" previewClassName="h-auto py-6">
<d />
</ComponentPreview>

### Bubble reactions [#bubble-reactions]

`BubbleReactions` sits on the edge of a bubble. Use `align="start"` for a top-right pin, `side="top"` for the lower edge. Children can be emoji or interactive buttons.

<ComponentPreview name="bubble-reactions-demo" title="bubble-reactions-demo.tsx" src="examples/bubble-reactions-demo.tsx" previewClassName="h-auto py-6">
<BubbleReactionsDemo />
</ComponentPreview>

### Collapsible bubble [#collapsible-bubble]

Long content can collapse into a preview. The trigger lives inside the bubble itself.

<ComponentPreview name="bubble-collapsible-demo" title="bubble-collapsible-demo.tsx" src="examples/bubble-collapsible-demo.tsx" previewClassName="h-auto py-6">
<BubbleCollapsibleDemo />
</ComponentPreview>

### Tooltip in reactions [#tooltip-in-reactions]

Place a `Tooltip` inside `BubbleReactions` to add hover context to actions.

<ComponentPreview name="bubble-tooltip-demo" title="bubble-tooltip-demo.tsx" src="examples/bubble-tooltip-demo.tsx" previewClassName="h-auto py-6">
<y />
</ComponentPreview>

### Popover in reactions [#popover-in-reactions]

Show inline error detail from a bubble without leaving the conversation.

<ComponentPreview name="bubble-popover-demo" title="bubble-popover-demo.tsx" src="examples/bubble-popover-demo.tsx" previewClassName="h-auto py-6">
<x />
</ComponentPreview>

### Scroll behavior [#scroll-behavior]

`MessageScroller` anchors the viewport, follows streamed replies, and shows a scroll-to-end button when the user scrolls up. Pass `messageId` on each `MessageScrollerItem` to support `scrollToMessage`.

<ComponentPreview name="message-scroller-demo" title="message-scroller-demo.tsx" src="examples/message-scroller-demo.tsx" previewClassName="h-auto py-6">
<MessageScrollerDemo />
</ComponentPreview>

### Streamed reply animation [#streamed-reply-animation]

`MessageAnimated` reads a `UIMessage`, extracts its text parts, and fades the bubble in. Pass `motion` to override the transition.

<ComponentPreview name="message-animated-demo" title="message-animated-demo.tsx" src="examples/message-animated-demo.tsx" previewClassName="h-auto py-8">
<MessageAnimatedDemo />
</ComponentPreview>

## API Reference [#api-reference]

All layout primitives (**MessageGroup**, **Message**, **MessageAvatar**, **MessageContent**, **MessageHeader**, **MessageFooter**, **BubbleGroup**, **MessageScroller**, **MessageScrollerViewport**, **MessageScrollerContent**) accept standard `div` attributes and `className`.

### Message [#message]

<PropsTable rows={[{"name":"align","type":"start | end","defaultValue":"start","description":"Side of the row the message content sits on."}]} />

### Bubble [#bubble]

<PropsTable rows={[{"name":"variant","type":"default | secondary | destructive | outline | ghost | muted | tinted","defaultValue":"default","description":"Visual style."},{"name":"align","type":"start | end","defaultValue":"start","description":"Self-align inside a Message row."}]} />

### BubbleContent [#bubblecontent]

<PropsTable rows={[{"name":"as","type":"React.ElementType","description":"Render as a different element or component. Defaults to div. Use as='a' or as={Link} for clickable bubbles."}]} />

### BubbleReactions [#bubblereactions]

<PropsTable rows={[{"name":"align","type":"start | end","defaultValue":"end","description":"Horizontal anchor side."},{"name":"side","type":"top | bottom","defaultValue":"bottom","description":"Vertical anchor side."}]} />

### MessageScrollerProvider [#messagescrollerprovider]

<PropsTable rows={[{"name":"autoScroll","type":"boolean","defaultValue":"true","description":"Follow new messages automatically when the user is at the end."},{"name":"defaultScrollPosition","type":"start | end | last-anchor","defaultValue":"end","description":"Initial scroll position on mount."},{"name":"scrollEdgeThreshold","type":"number","defaultValue":"16","description":"Pixels from the edge to consider scrollable."},{"name":"scrollMargin","type":"number","defaultValue":"0","description":"Offset from the viewport edge."},{"name":"scrollPreviousItemPeek","type":"number","defaultValue":"40","description":"Amount of the previous item kept visible when jumping to a message."}]} />

### MessageScrollerViewport [#messagescrollerviewport]

<PropsTable rows={[{"name":"preserveScrollOnPrepend","type":"boolean","description":"Preserve the current scroll offset when items are prepended (e.g. loading older messages)."}]} />

### MessageScrollerItem [#messagescrolleritem]

<PropsTable rows={[{"name":"messageId","type":"string","description":"Anchor id used by scrollToMessage and visibility tracking."},{"name":"scrollAnchor","type":"boolean","defaultValue":"false","description":"Mark this item as the anchor for prepend-scroll preservation."}]} />

### MessageScrollerButton [#messagescrollerbutton]

<PropsTable rows={[{"name":"direction","type":"start | end","defaultValue":"end","description":"Jump to the start or end of the transcript."},{"name":"behavior","type":"smooth | auto | instant","defaultValue":"smooth","description":"Scroll behavior."},{"name":"render","type":"React.ReactElement","description":"Render prop; the target element gets data-active and onClick merged."},{"name":"variant","type":"Button variant","defaultValue":"secondary","description":"Passed through to the rendered button."},{"name":"size","type":"Button size","defaultValue":"icon-sm","description":"Passed through to the rendered button."}]} />

### MessageAnimated [#messageanimated]

<PropsTable rows={[{"name":"message","type":"UIMessage","description":"The message to render. Text parts are concatenated."},{"name":"motion","type":"string","description":"CSS transition override; e.g. 200 ease-out or 300 cubic-bezier(...)."},{"name":"scrollAnchor","type":"boolean","defaultValue":"false","description":"Forwarded to the underlying MessageScrollerItem."}]} />

## Hooks [#hooks]

The three hooks must be called inside `<MessageScrollerProvider>`. They return values from the nearest provider context.

### useMessageScroller() [#usemessagescroller]

Returns imperative scroll methods:

- `scrollToEnd(opts?)` - scroll the viewport to the bottom; returns `true` if the viewport exists.
- `scrollToStart(opts?)` - scroll to the top.
- `scrollToMessage(messageId, opts?)` - scroll a specific item into view by its `messageId`.

Each method accepts `{ behavior?: ScrollBehavior, align?: ScrollAlign, scrollMargin?: number }`.

### useMessageScrollerScrollable() [#usemessagescrollerscrollable]

Returns `{ start: boolean, end: boolean }` - whether the viewport can scroll further in each direction. Useful to render custom scroll buttons or fade edges.

### useMessageScrollerVisibility() [#usemessagescrollervisibility]

Returns `{ currentAnchorId: string | null, visibleMessageIds: string[] }`. `currentAnchorId` is the topmost visible item; `visibleMessageIds` lists every item currently inside the viewport.

## Accessibility [#accessibility]

- `MessageScrollerButton` renders a native `<button>` with an `sr-only` label (Scroll to end / Scroll to start).
- `MessageScrollerViewport` uses `overscroll-contain` so nested scroll contexts do not chain to the page.
- `MessageScrollerItem` sets `content-visibility: auto` for off-screen performance; screen readers still announce off-screen items when navigating.
- `Bubble` renders a plain `<div>`. Use `BubbleContent` with `as="a"` or `as={Link}` for clickable bubbles; do not nest interactive content inside a non-interactive bubble.

## Best Practices [#best-practices]

- **Always wrap the scroller in `MessageScrollerProvider`.** The provider owns the scroll context; children throw if the context is missing.
- **Pass `messageId` on every `MessageScrollerItem`.** Without it, `scrollToMessage` and visibility tracking cannot find the item.
- **Use `MessageAnimated` for streamed replies.** It expects a `UIMessage` from the AI SDK and handles text extraction and fade-in.
- **Reduce motion is honored automatically.** When the OS requests reduced motion, transitions are disabled; `motion` values are ignored.
- **Prefer `Bubble` variants over custom colors.** The seven built-in variants cover the common message types.