Message

Lays out one turn in a conversation, with an avatar, a header, the message content, a footer and alignment.

ME
I'm merging the parser fix now.
GH
Did the fuzz tests run on it?
ME
For an hour, with no failures.
Delivered
GH
Good. An hour is enough for this one.
Merge it, and I'll watch the nightly run.
Grace is typing...
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { Bubble, BubbleContent, BubbleGroup, BubbleReactions } from "@/components/ui/bubble"
import { Marker, MarkerContent } from "@/components/ui/marker"
import { Message, MessageAvatar, MessageContent, MessageFooter } from "@/components/ui/message"
import { VStack } from "@/components/ui/stack"
import { shimmerStyles } from "@/lib/shimmer"
import { widths } from "@/theme/widths"

export default function MessageDemo() {
  return (
    <VStack gap={6} xstyle={widths.sm}>
      <Message align="end">
        <MessageAvatar>
          <Avatar>
            <AvatarFallback>ME</AvatarFallback>
          </Avatar>
        </MessageAvatar>
        <MessageContent>
          <Bubble>
            <BubbleContent>I&apos;m merging the parser fix now.</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
      <Message>
        <MessageAvatar>
          <Avatar>
            <AvatarFallback>GH</AvatarFallback>
          </Avatar>
        </MessageAvatar>
        <MessageContent>
          <Bubble variant="secondary">
            <BubbleContent>Did the fuzz tests run on it?</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
      <Message align="end">
        <MessageAvatar>
          <Avatar>
            <AvatarFallback>ME</AvatarFallback>
          </Avatar>
        </MessageAvatar>
        <MessageContent>
          <Bubble>
            <BubbleContent>For an hour, with no failures.</BubbleContent>
          </Bubble>
        </MessageContent>
        <MessageFooter>Delivered</MessageFooter>
      </Message>
      <Message>
        <MessageAvatar>
          <Avatar>
            <AvatarFallback>GH</AvatarFallback>
          </Avatar>
        </MessageAvatar>
        <MessageContent>
          <BubbleGroup>
            <Bubble variant="secondary">
              <BubbleContent>Good. An hour is enough for this one.</BubbleContent>
            </Bubble>
            <Bubble variant="secondary">
              <BubbleContent>Merge it, and I&apos;ll watch the nightly run.</BubbleContent>
              <BubbleReactions role="img" aria-label="Reaction: thumbs up">
                <span>👍</span>
              </BubbleReactions>
            </Bubble>
          </BubbleGroup>
        </MessageContent>
      </Message>
      <Marker role="status">
        <MarkerContent xstyle={shimmerStyles.base}>Grace is typing...</MarkerContent>
      </Marker>
    </VStack>
  )
}

Message lays out one turn: the avatar, the side, a header above the content and a footer below it. The content itself is usually a Bubble, which is only the surface. An assistant's reply, a reasoning step or a tool call can sit in the same place.

Installation

pnpm dlx shadcn@latest add @arene/message

Needs the arene setup first. Also adds Bubble and Stack.

Usage

import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { Bubble, BubbleContent } from "@/components/ui/bubble"
import { Message, MessageAvatar, MessageContent } from "@/components/ui/message"
<Message>
  <MessageAvatar>
    <Avatar>
      <AvatarFallback>AL</AvatarFallback>
    </Avatar>
  </MessageAvatar>
  <MessageContent>
    <Bubble variant="secondary">
      <BubbleContent>I reran the benchmark on both machines.</BubbleContent>
    </Bubble>
  </MessageContent>
</Message>

Composition

Message
├── MessageAvatar
├── MessageHeader
├── MessageContent
│   └── Bubble
└── MessageFooter

MessageGroup stacks back-to-back messages from one sender:

MessageGroup
├── Message
└── Message

The header and the footer are children of the message, not of MessageContent. The message is a grid, and the content is its one fixed cell: the header takes a row above it, the footer a row below, and the avatar a column beside it, each only when it is there. Write them in reading order, as above, so a screen reader meets them in the order they are drawn.

align on the message moves the whole turn. The avatar goes to that side, and the header, the content and the footer line up with it. A Bubble inside takes the message's side, so it needs no align of its own.

Avatar

Use MessageAvatar to put an avatar beside the content. It sits level with the bottom of the content, so a footer below the last bubble does not push it down. With align="end" it moves to the end.

AT
The nightly import stopped halfway through.
ME
What does the log say?
AT
This is the last entry before it stopped.
The import ran out of memory on the largest file. The other files finished, so only that one needs to run again.
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { Bubble, BubbleContent, BubbleGroup } from "@/components/ui/bubble"
import { Message, MessageAvatar, MessageContent } from "@/components/ui/message"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"

export default function MessageAvatarDemo() {
  return (
    <VStack gap={6} xstyle={widths.sm}>
      <Message>
        <MessageAvatar>
          <Avatar>
            <AvatarFallback>AT</AvatarFallback>
          </Avatar>
        </MessageAvatar>
        <MessageContent>
          <Bubble variant="secondary">
            <BubbleContent>The nightly import stopped halfway through.</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
      <Message align="end">
        <MessageAvatar>
          <Avatar>
            <AvatarFallback>ME</AvatarFallback>
          </Avatar>
        </MessageAvatar>
        <MessageContent>
          <Bubble>
            <BubbleContent>What does the log say?</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
      <Message>
        <MessageAvatar>
          <Avatar>
            <AvatarFallback>AT</AvatarFallback>
          </Avatar>
        </MessageAvatar>
        <MessageContent>
          <BubbleGroup>
            <Bubble variant="secondary">
              <BubbleContent>This is the last entry before it stopped.</BubbleContent>
            </Bubble>
            <Bubble variant="secondary">
              <BubbleContent>
                The import ran out of memory on the largest file. The other files finished, so only
                that one needs to run again.
              </BubbleContent>
            </Bubble>
          </BubbleGroup>
        </MessageContent>
      </Message>
    </VStack>
  )
}

Group

MessageGroup stacks back-to-back messages from one sender. Put an empty MessageAvatar on the earlier messages so they line up with the avatar on the last one. gap takes a step on the spacing scale and defaults to 1.

I reran the benchmark on both machines.
AL
The numbers agree within two percent, so the speedup holds.
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { Bubble, BubbleContent } from "@/components/ui/bubble"
import { Message, MessageAvatar, MessageContent, MessageGroup } from "@/components/ui/message"
import { widths } from "@/theme/widths"

export default function MessageGroupDemo() {
  return (
    <MessageGroup xstyle={widths.sm}>
      <Message>
        <MessageAvatar />
        <MessageContent>
          <Bubble variant="secondary">
            <BubbleContent>I reran the benchmark on both machines.</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
      <Message>
        <MessageAvatar>
          <Avatar>
            <AvatarFallback>AL</AvatarFallback>
          </Avatar>
        </MessageAvatar>
        <MessageContent>
          <Bubble variant="secondary">
            <BubbleContent>
              The numbers agree within two percent, so the speedup holds.
            </BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
    </MessageGroup>
  )
}

MessageHeader holds the sender's name, and MessageFooter holds details such as whether the message was delivered or read. Both are indented to line up with the text inside a bubble, ghost included.

Ada
I already compared the two datasets.
Send the summary to the team. Ask Ada if anything looks off.
Read Yesterday
import { Bubble, BubbleContent } from "@/components/ui/bubble"
import { Message, MessageContent, MessageFooter, MessageHeader } from "@/components/ui/message"
import { Text } from "@/components/ui/text"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"

export default function MessageHeaderFooter() {
  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Message>
        <MessageHeader>Ada</MessageHeader>
        <MessageContent>
          <Bubble variant="secondary">
            <BubbleContent>I already compared the two datasets.</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
      <Message align="end">
        <MessageContent>
          <Bubble>
            <BubbleContent>
              Send the summary to the team. Ask Ada if anything looks off.
            </BubbleContent>
          </Bubble>
        </MessageContent>
        <MessageFooter>
          Read <Text weight="normal">Yesterday</Text>
        </MessageFooter>
      </Message>
    </VStack>
  )
}

Actions

Put message actions in MessageFooter: copy, retry, or feedback toggles. Use ghost icon buttons, each with a Tooltip and an aria-label, and set aria-pressed on a toggle.

The checksum fails because the cached copy of the archive is stale.
I'll clear the cache and run it again.
Failed to send
"use client"

import { useEffect, useState, type ComponentProps } from "react"
import * as stylex from "@stylexjs/stylex"
import { Bubble, BubbleContent } from "@/components/ui/bubble"
import { Button } from "@/components/ui/button"
import { Message, MessageContent, MessageFooter } from "@/components/ui/message"
import { Text } from "@/components/ui/text"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"
import { VStack } from "@/components/ui/stack"
import { color } from "@/theme/tokens.stylex"
import { widths } from "@/theme/widths"
import { ArrowClockwiseIcon } from "@phosphor-icons/react/dist/csr/ArrowClockwise"
import { CheckIcon } from "@phosphor-icons/react/dist/csr/Check"
import { CopyIcon } from "@phosphor-icons/react/dist/csr/Copy"
import { ThumbsDownIcon } from "@phosphor-icons/react/dist/csr/ThumbsDown"
import { ThumbsUpIcon } from "@phosphor-icons/react/dist/csr/ThumbsUp"

const styles = stylex.create({
  failed: { color: color.destructive },
})

const reply = "The checksum fails because the cached copy of the archive is stale."

function MessageAction({ label, ...props }: ComponentProps<typeof Button> & { label: string }) {
  return (
    <Tooltip>
      <TooltipTrigger
        render={<Button variant="ghost" size="icon-sm" aria-label={label} {...props} />}
      />
      <TooltipContent>{label}</TooltipContent>
    </Tooltip>
  )
}

export default function MessageActions() {
  const [copied, setCopied] = useState(false)
  const [feedback, setFeedback] = useState<"like" | "dislike" | null>(null)

  useEffect(() => {
    if (!copied) return
    const timeout = setTimeout(() => setCopied(false), 2000)
    return () => clearTimeout(timeout)
  }, [copied])

  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Message>
        <MessageContent>
          <Bubble variant="secondary">
            <BubbleContent>{reply}</BubbleContent>
          </Bubble>
        </MessageContent>
        <MessageFooter>
          <MessageAction
            label={copied ? "Copied" : "Copy"}
            onClick={() => {
              void navigator.clipboard?.writeText(reply)
              setCopied(true)
            }}
          >
            {copied ? <CheckIcon aria-hidden="true" /> : <CopyIcon aria-hidden="true" />}
          </MessageAction>
          <MessageAction
            label="Good response"
            aria-pressed={feedback === "like"}
            onClick={() => setFeedback(feedback === "like" ? null : "like")}
          >
            <ThumbsUpIcon aria-hidden="true" weight={feedback === "like" ? "fill" : "regular"} />
          </MessageAction>
          <MessageAction
            label="Bad response"
            aria-pressed={feedback === "dislike"}
            onClick={() => setFeedback(feedback === "dislike" ? null : "dislike")}
          >
            <ThumbsDownIcon
              aria-hidden="true"
              weight={feedback === "dislike" ? "fill" : "regular"}
            />
          </MessageAction>
        </MessageFooter>
      </Message>
      <Message align="end">
        <MessageContent>
          <Bubble>
            <BubbleContent>I&apos;ll clear the cache and run it again.</BubbleContent>
          </Bubble>
        </MessageContent>
        <MessageFooter>
          <Text weight="normal" xstyle={styles.failed}>
            Failed to send
          </Text>
          <MessageAction label="Retry">
            <ArrowClockwiseIcon aria-hidden="true" />
          </MessageAction>
        </MessageFooter>
      </Message>
    </VStack>
  )
}

Markdown

Put an assistant's reply in a ghost bubble, so it is unframed and can take the full width. It keeps the bubble's padding, so its text lines up with the header and the footer.

Can a reply include formatting?

Yes. Three things make it work:

  1. Pass assistant text through a Markdown renderer.
  2. Show user messages exactly as they were typed.
  3. Put the reply in a ghost bubble so it has no frame.
import * as stylex from "@stylexjs/stylex"
import { Bubble, BubbleContent } from "@/components/ui/bubble"
import { Message, MessageContent } from "@/components/ui/message"
import { VStack } from "@/components/ui/stack"
import { color, font, leading, radius, space, text } from "@/theme/tokens.stylex"
import { widths } from "@/theme/widths"

const styles = stylex.create({
  list: { paddingInlineStart: space.s5, listStyleType: "decimal" },
  code: {
    paddingInline: space.s1,
    borderRadius: radius.sm,
    backgroundColor: color.muted,
    fontFamily: font.mono,
    fontSize: text.code,
    lineHeight: leading.sm,
  },
})

export default function MessageMarkdown() {
  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Message align="end">
        <MessageContent>
          <Bubble>
            <BubbleContent>Can a reply include formatting?</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
      <Message>
        <MessageContent>
          <Bubble variant="ghost">
            <BubbleContent>
              <VStack gap={2}>
                <p>Yes. Three things make it work:</p>
                <ol {...stylex.props(styles.list)}>
                  <li>
                    Pass assistant text through <strong>a Markdown renderer</strong>.
                  </li>
                  <li>Show user messages exactly as they were typed.</li>
                  <li>
                    Put the reply in a <code {...stylex.props(styles.code)}>ghost</code> bubble so
                    it has no frame.
                  </li>
                </ol>
              </VStack>
            </BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
    </VStack>
  )
}

Attachment

Put an Attachment in MessageContent beside the bubble, above it or below it. It takes the message's side like a bubble does.

Office corridor with glass walls
Here is a photo of the new floor. Can you put it on the cover of the move plan?
Done. The move plan now opens with the photo on its cover page.
move-plan.pdfPDF · 3.4 MB
Thanks, that works.
import { DownloadSimpleIcon } from "@phosphor-icons/react/dist/csr/DownloadSimple"
import { FileTextIcon } from "@phosphor-icons/react/dist/csr/FileText"
import {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentMedia,
  AttachmentTitle,
} from "@/components/ui/attachment"
import { Bubble, BubbleContent } from "@/components/ui/bubble"
import { Message, MessageContent } from "@/components/ui/message"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"

export default function MessageAttachment() {
  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Message align="end">
        <MessageContent>
          <Attachment orientation="vertical">
            <AttachmentMedia variant="image">
              <img
                src="https://images.unsplash.com/photo-1497366754035-f200968a6e72?w=900&auto=format&fit=crop&q=80"
                alt="Office corridor with glass walls"
              />
            </AttachmentMedia>
          </Attachment>
          <Bubble>
            <BubbleContent>
              Here is a photo of the new floor. Can you put it on the cover of the move plan?
            </BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
      <Message>
        <MessageContent>
          <Bubble variant="secondary">
            <BubbleContent>
              Done. The move plan now opens with the photo on its cover page.
            </BubbleContent>
          </Bubble>
          <Attachment>
            <AttachmentMedia>
              <FileTextIcon aria-hidden="true" />
            </AttachmentMedia>
            <AttachmentContent>
              <AttachmentTitle>move-plan.pdf</AttachmentTitle>
              <AttachmentDescription>PDF · 3.4 MB</AttachmentDescription>
            </AttachmentContent>
            <AttachmentActions>
              <AttachmentAction aria-label="Download move-plan.pdf" variant="secondary">
                <DownloadSimpleIcon aria-hidden="true" />
              </AttachmentAction>
            </AttachmentActions>
          </Attachment>
        </MessageContent>
      </Message>
      <Message align="end">
        <MessageContent>
          <Bubble>
            <BubbleContent>Thanks, that works.</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
    </VStack>
  )
}

Accessibility

Message is a presentational layout. Accessibility comes from what you put in it.

Icon-only actions

Most footer actions show only an icon. Each one needs an aria-label.

<MessageFooter>
  <Button variant="ghost" size="icon-sm" aria-label="Copy">
    <CopyIcon aria-hidden="true" />
  </Button>
</MessageFooter>

Status updates

For a message in progress, use a Marker with role="status", so assistive technology announces the update when it appears.

<Marker role="status">
  <MarkerContent>Rerunning the benchmark...</MarkerContent>
</Marker>

API reference

Pass render to replace a part's element or compose it with another component. Every part also takes xstyle, className and style.

Message

Renders a div. It provides its align to the bubbles inside it.

PropTypeDefault
align"start" | "end""start"

MessageGroup

Renders a div: a vertical Stack whose only layout prop is gap.

PropTypeDefault
gapSpacingStep1

MessageAvatar

Renders a div, at least 32px wide, at the bottom of the turn. Empty, it keeps the column so grouped messages line up.

MessageContent

Renders a div: a vertical Stack whose only layout prop is gap. It holds the bubbles and anything beside them, and lines them up with the message's side.

PropTypeDefault
gapSpacingStep1.5

MessageHeader

Renders a div in the row above the content, in small muted type, indented to line up with the text in a bubble.

MessageFooter

Renders a div in the row below the content, styled like the header.

messageStyles

The style maps behind the component. Spread them onto any element.

KeyWhat it is
baseThe turn's grid, its gaps and its type
alignsOne entry per align
avatarThe avatar's box, level with the bottom of the content
avatarSidesThe avatar's column, one entry per align
contentThe content's cell, width and word breaking
headerThe header's row above the content, type, colour, indent
footerThe footer's row below the content, type, colour, indent

Data attributes

AttributeOnEffect
data-slot="message"the rootTargets the message from a parent
data-alignthe rootReflects align
data-slot="message-avatar"the avatarTargets the avatar from a parent
data-slot="message-content"the contentTargets the content from a parent
data-slot="message-header"the headerTargets the header from a parent
data-slot="message-footer"the footerTargets the footer from a parent
data-slot="message-group"the groupTargets the group from a parent