Bubble

The surface for one piece of a conversation, with variants, alignment, groups, reactions and collapsible content.

Morning. Is the build green yet?
Not yet. Two date tests still fail.
Both fail on the year 1900. The leap year rule treats it as a leap year.
Divisible by 100 but not by 400, so no.
Right. I added that case to the rule, and both tests pass now. The build is running.
import { Bubble, BubbleContent, BubbleGroup, BubbleReactions } from "@/components/ui/bubble"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"

export default function BubbleDemo() {
  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Bubble align="end">
        <BubbleContent>Morning. Is the build green yet?</BubbleContent>
      </Bubble>
      <BubbleGroup>
        <Bubble variant="secondary">
          <BubbleContent>Not yet. Two date tests still fail.</BubbleContent>
        </Bubble>
        <Bubble variant="secondary">
          <BubbleContent>
            Both fail on the year 1900. The leap year rule treats it as a leap year.
          </BubbleContent>
          <BubbleReactions role="img" aria-label="Reaction: thumbs up">
            <span>👍</span>
          </BubbleReactions>
        </Bubble>
      </BubbleGroup>
      <Bubble align="end">
        <BubbleContent>Divisible by 100 but not by 400, so no.</BubbleContent>
      </Bubble>
      <Bubble variant="secondary">
        <BubbleContent>
          Right. I added that case to the rule, and both tests pass now. The build is running.
        </BubbleContent>
        <BubbleReactions role="img" aria-label="Reactions: thumbs up, fire, eyes, and 2 more">
          <span>👍</span>
          <span>🔥</span>
          <span>👀</span>
          <span>+2</span>
        </BubbleReactions>
      </Bubble>
    </VStack>
  )
}

Bubble is the surface of one piece of conversation: chat text, short structured output, a quoted reply, a suggestion. The avatar, the sender's name, the time and the message actions belong to the turn around it, which is Message.

Installation

pnpm dlx shadcn@latest add @arene/bubble

Needs the arene setup first. Also adds Stack.

Usage

import { Bubble, BubbleContent, BubbleReactions } from "@/components/ui/bubble"
<Bubble>
  <BubbleContent>I renamed the config key and updated the two files that read it.</BubbleContent>
  <BubbleReactions role="img" aria-label="Reaction: thumbs up">
    <span>👍</span>
  </BubbleReactions>
</Bubble>

Composition

Bubble
├── BubbleContent
└── BubbleReactions

Use BubbleGroup for consecutive bubbles from the same sender:

BubbleGroup
├── Bubble
│   └── BubbleContent
└── Bubble
    └── BubbleContent

Bubble sets the variant and the side, and BubbleContent draws the surface from them. A bubble is as wide as its content, up to 80% of its container. A ghost bubble can take the full width.

Variants

Use variant to change the surface.

The default variant has the primary fill.
This is the secondary variant, the neutral fill for the other side of the conversation.
The outline variant has a border and no fill.
The destructive variant marks errors.
The ghost variant has no frame. It suits assistant text and other content that reads better unboxed, and it takes the full width of the container.
import { Bubble, BubbleContent, BubbleReactions } from "@/components/ui/bubble"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"

export default function BubbleVariants() {
  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Bubble align="end">
        <BubbleContent>The default variant has the primary fill.</BubbleContent>
      </Bubble>
      <Bubble variant="secondary">
        <BubbleContent>
          This is the secondary variant, the neutral fill for the other side of the conversation.
        </BubbleContent>
        <BubbleReactions role="img" aria-label="Reaction: thumbs up">
          <span>👍</span>
        </BubbleReactions>
      </Bubble>
      <Bubble variant="outline" align="end">
        <BubbleContent>The outline variant has a border and no fill.</BubbleContent>
      </Bubble>
      <Bubble variant="destructive">
        <BubbleContent>The destructive variant marks errors.</BubbleContent>
        <BubbleReactions role="img" aria-label="Reaction: fire">
          <span>🔥</span>
        </BubbleReactions>
      </Bubble>
      <Bubble variant="ghost">
        <BubbleContent>
          The ghost variant has no frame. It suits assistant text and other content that reads
          better unboxed, and it takes the full width of the container.
        </BubbleContent>
      </Bubble>
    </VStack>
  )
}
VariantUse
defaultThe primary fill, usually for the current user
secondaryThe neutral fill, usually for the other side
outlineA hairline edge and no fill, for options and links
ghostNo fill and no edge, for assistant text and rich output
destructiveA destructive tint, for errors and failed actions

The names match Button and Badge. A ghost bubble keeps the padding of the others, so its text starts where theirs does and lines up with a Message header or footer.

Alignment

Use align to put the bubble at the start or the end of the conversation.

Start is the default side. It suits the other person in the conversation.
End moves the bubble to the far side. It suits the user's own messages.
import { Bubble, BubbleContent } from "@/components/ui/bubble"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"

export default function BubbleAlignment() {
  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Bubble variant="secondary">
        <BubbleContent>
          Start is the default side. It suits the other person in the conversation.
        </BubbleContent>
      </Bubble>
      <Bubble align="end">
        <BubbleContent>
          End moves the bubble to the far side. It suits the user&apos;s own messages.
        </BubbleContent>
      </Bubble>
    </VStack>
  )
}

The bubble's parent has to be a flex column for align to move it, as BubbleGroup, MessageContent and a VStack are. Inside a Message, a bubble with no align takes the message's, so set align once on the message.

Bubble group

Use BubbleGroup to stack consecutive bubbles from the same sender. Set align on each Bubble, not on the group. gap takes a step on the spacing scale and defaults to 1.

What are you seeing?
The totals are off.
They matched this morning.
Can you find out why?
The sum switched to 32-bit floats today. Small values now get lost next to large ones.
import { Bubble, BubbleContent, BubbleGroup, BubbleReactions } from "@/components/ui/bubble"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"

export default function BubbleGroupDemo() {
  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Bubble variant="secondary">
        <BubbleContent>What are you seeing?</BubbleContent>
      </Bubble>
      <BubbleGroup>
        <Bubble align="end">
          <BubbleContent>The totals are off.</BubbleContent>
        </Bubble>
        <Bubble align="end">
          <BubbleContent>They matched this morning.</BubbleContent>
        </Bubble>
        <Bubble align="end">
          <BubbleContent>Can you find out why?</BubbleContent>
          <BubbleReactions align="start" role="img" aria-label="Reaction: eyes">
            <span>👀</span>
          </BubbleReactions>
        </Bubble>
      </BubbleGroup>
      <Bubble variant="secondary">
        <BubbleContent>
          The sum switched to 32-bit floats today. Small values now get lost next to large ones.
        </BubbleContent>
      </Bubble>
    </VStack>
  )
}

Pass render to BubbleContent to make the bubble a link or a button. It then takes a hover step and shows a focus ring.

What do you need help with?
import { Bubble, BubbleContent, BubbleGroup } from "@/components/ui/bubble"
import { VStack } from "@/components/ui/stack"
import { toast } from "@/components/ui/toast"
import { widths } from "@/theme/widths"

const replies = [
  "I can't sign in",
  "I have a question about billing",
  "None of these. Contact support.",
]

export default function BubbleLinkButton() {
  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Bubble variant="secondary">
        <BubbleContent>What do you need help with?</BubbleContent>
      </Bubble>
      <BubbleGroup>
        {replies.map((reply) => (
          <Bubble key={reply} variant="outline" align="end">
            <BubbleContent
              render={<button type="button" onClick={() => toast.add({ title: reply })} />}
            >
              {reply}
            </BubbleContent>
          </Bubble>
        ))}
      </BubbleGroup>
      <Bubble variant="outline">
        <BubbleContent render={<a href="/docs/components/message" />}>
          Read about Message, which lays out a whole turn.
        </BubbleContent>
      </Bubble>
    </VStack>
  )
}
<Bubble variant="outline" align="end">
  <BubbleContent render={<button type="button" onClick={onReply} />}>I can't sign in</BubbleContent>
</Bubble>

Reactions

Use BubbleReactions for reactions or quick actions. It overlaps the bubble's edge. side picks the edge and align the corner. Leave vertical space between bubbles that carry reactions, as the example does with a larger gap.

The function is pure, so I left the tests out.
Pure functions are the easiest to test. I'll write a few property tests and report back.
All 200 generated cases pass, including the empty input.
This deletes the old fixtures. Should I run it?
import { Bubble, BubbleContent, BubbleReactions } from "@/components/ui/bubble"
import { Button } from "@/components/ui/button"
import { VStack } from "@/components/ui/stack"
import { toast } from "@/components/ui/toast"
import { widths } from "@/theme/widths"

export default function BubbleReactionsDemo() {
  return (
    <VStack gap={12} xstyle={widths.sm}>
      <Bubble variant="secondary" align="end">
        <BubbleContent>The function is pure, so I left the tests out.</BubbleContent>
        <BubbleReactions align="start" role="img" aria-label="Reactions: thumbs up, surprised">
          <span>👍</span>
          <span>😮</span>
        </BubbleReactions>
      </Bubble>
      <Bubble variant="secondary">
        <BubbleContent>
          Pure functions are the easiest to test. I&apos;ll write a few property tests and report
          back.
        </BubbleContent>
        <BubbleReactions role="img" aria-label="Reactions: eyes, rocket, and 2 more">
          <span>👀</span>
          <span>🚀</span>
          <span>+2</span>
        </BubbleReactions>
      </Bubble>
      <Bubble align="end">
        <BubbleContent>All 200 generated cases pass, including the empty input.</BubbleContent>
        <BubbleReactions
          side="top"
          align="start"
          role="img"
          aria-label="Reactions: party popper, clapping hands"
        >
          <span>🎉</span>
          <span>👏</span>
        </BubbleReactions>
      </Bubble>
      <Bubble variant="destructive">
        <BubbleContent>This deletes the old fixtures. Should I run it?</BubbleContent>
        <BubbleReactions>
          <Button
            variant="ghost"
            size="xs"
            onClick={() => toast.add({ title: "Deleting the old fixtures" })}
          >
            Delete them
          </Button>
        </BubbleReactions>
      </Bubble>
    </VStack>
  )
}

Show more

Compose long content with Collapsible. Show the first paragraph, put the rest in CollapsibleContent, and follow it with a CollapsibleTrigger that reads Show more or Show less.

Did the contrast review find anything?

The contrast check found two text colours that fall below 4.5:1 on the muted background.

"use client"

import { useState } from "react"
import * as stylex from "@stylexjs/stylex"
import { Bubble, BubbleContent } from "@/components/ui/bubble"
import { Button } from "@/components/ui/button"
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
  collapsibleStyles,
} from "@/components/ui/collapsible"
import { VStack } from "@/components/ui/stack"
import { color } from "@/theme/tokens.stylex"
import { widths } from "@/theme/widths"
import { CaretDownIcon } from "@phosphor-icons/react/dist/csr/CaretDown"

const styles = stylex.create({
  trigger: { paddingInline: 0, color: color.mutedForeground },
})

const [summary, ...details] = [
  "The contrast check found two text colours that fall below 4.5:1 on the muted background.",
  "I measured every token pair the docs use for body text, captions and placeholders, in both the light and the dark scheme.",
  "Body text and captions pass. Placeholder text fails in the light scheme, and the disabled label fails in both, each by a small margin.",
  "I suggest raising the lightness of those two tokens only, so the rest of the palette and every component built on it stays the same.",
]

export default function BubbleCollapsible() {
  const [open, setOpen] = useState(false)

  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Bubble variant="secondary">
        <BubbleContent>Did the contrast review find anything?</BubbleContent>
      </Bubble>
      <Bubble variant="secondary" align="end">
        <BubbleContent>
          <Collapsible open={open} onOpenChange={setOpen}>
            <p>{summary}</p>
            <CollapsibleContent>
              <VStack gap={2} paddingBlockStart={2}>
                {details.map((paragraph) => (
                  <p key={paragraph}>{paragraph}</p>
                ))}
              </VStack>
            </CollapsibleContent>
            <CollapsibleTrigger render={<Button variant="link" xstyle={styles.trigger} />}>
              {open ? "Show less" : "Show more"}
              <CaretDownIcon aria-hidden="true" {...stylex.props(collapsibleStyles.chevron)} />
            </CollapsibleTrigger>
          </Collapsible>
        </BubbleContent>
      </Bubble>
    </VStack>
  )
}

Tooltip

Place a Tooltip in the reactions for details that appear on hover, such as the time a message was read.

Did you rename the config key?
Yes, and I updated both files that read it.
import { Bubble, BubbleContent, BubbleReactions } from "@/components/ui/bubble"
import { Button } from "@/components/ui/button"
import { VStack } from "@/components/ui/stack"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"
import { widths } from "@/theme/widths"
import { ChecksIcon } from "@phosphor-icons/react/dist/csr/Checks"

export default function BubbleTooltip() {
  return (
    <VStack gap={4} xstyle={widths.sm}>
      <Bubble variant="secondary">
        <BubbleContent>Did you rename the config key?</BubbleContent>
      </Bubble>
      <Bubble align="end">
        <BubbleContent>Yes, and I updated both files that read it.</BubbleContent>
        <BubbleReactions>
          <Tooltip>
            <TooltipTrigger
              render={<Button variant="ghost" size="icon-xs" aria-label="Read receipt" />}
            >
              <ChecksIcon aria-hidden="true" />
            </TooltipTrigger>
            <TooltipContent>Read on Mar 14, 2026 at 3:15 PM</TooltipContent>
          </Tooltip>
        </BubbleReactions>
      </Bubble>
    </VStack>
  )
}

Popover

Pair a bubble with a Popover to show more detail on demand, such as the full error behind a failed action.

Run the migration script.
The migration stopped with an error.
import { Bubble, BubbleContent, BubbleReactions } from "@/components/ui/bubble"
import { Button } from "@/components/ui/button"
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"
import { InfoIcon } from "@phosphor-icons/react/dist/csr/Info"

export default function BubblePopover() {
  return (
    <VStack gap={4} xstyle={widths.sm}>
      <Bubble align="end">
        <BubbleContent>Run the migration script.</BubbleContent>
      </Bubble>
      <Bubble variant="destructive">
        <BubbleContent>The migration stopped with an error.</BubbleContent>
        <BubbleReactions>
          <Popover>
            <PopoverTrigger
              render={<Button variant="ghost" size="icon-xs" aria-label="Show error details" />}
            >
              <InfoIcon aria-hidden="true" />
            </PopoverTrigger>
            <PopoverContent>
              <PopoverHeader>
                <PopoverTitle>Migration failed with exit code 1</PopoverTitle>
                <PopoverDescription>
                  error: relation &quot;measurements&quot; does not exist
                </PopoverDescription>
              </PopoverHeader>
            </PopoverContent>
          </Popover>
        </BubbleReactions>
      </Bubble>
    </VStack>
  )
}

Rich content

A ghost bubble holds paragraphs, lists and inline code with no frame around them. Render your markdown output inside BubbleContent.

What is a ghost bubble for?

A ghost bubble has no frame, which suits assistant text, rich content and anything else that reads better unboxed.

It takes the full width of the container, and inline code sits in the text the way it would in a document.

import * as stylex from "@stylexjs/stylex"
import { Bubble, BubbleContent } from "@/components/ui/bubble"
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({
  code: {
    paddingInline: space.s1,
    borderRadius: radius.sm,
    backgroundColor: color.muted,
    fontFamily: font.mono,
    fontSize: text.code,
    lineHeight: leading.sm,
  },
})

export default function BubbleMarkdown() {
  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Bubble align="end" variant="secondary">
        <BubbleContent>
          What is a <strong>ghost</strong> bubble for?
        </BubbleContent>
      </Bubble>
      <Bubble variant="ghost">
        <BubbleContent>
          <VStack gap={3}>
            <p>
              A ghost bubble has no frame, which suits assistant text, <strong>rich content</strong>{" "}
              and anything else that reads better unboxed.
            </p>
            <p>
              It takes the full width of the container, and inline{" "}
              <code {...stylex.props(styles.code)}>code</code> sits in the text the way it would in
              a document.
            </p>
          </VStack>
        </BubbleContent>
      </Bubble>
    </VStack>
  )
}

Accessibility

Bubble is a presentational surface. Put conversation semantics on the container around it.

Labelling reactions

A screen reader reads each emoji on its own and announces +8 as "plus eight". Give the row role="img" and an aria-label so it is announced once. role="img" also hides the emoji inside it, so they need no aria-hidden.

<BubbleReactions role="img" aria-label="Reactions: thumbs up, fire, and 8 more">
  <span>👍</span>
  <span>🔥</span>
  <span>+8</span>
</BubbleReactions>

When reactions are interactive, render buttons, and give an icon-only button an aria-label.

Interactive bubbles

Render a clickable bubble as a real button or a through render, so it is focusable and has the right role. Its text is its accessible name.

Meaning beyond colour

The variants signal role and tone through colour. Pair them with text, alignment or an icon. A destructive bubble should say what failed in its text.

API reference

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

Bubble

Renders a div.

PropTypeDefault
variant"default" | "secondary" | "outline" | "ghost" | "destructive""default"
align"start" | "end"the message's, else "start"

BubbleContent

Renders a div. It reads the variant and the side from the Bubble around it, and draws the default surface outside one.

BubbleReactions

Renders a div, positioned on the bubble's edge.

PropTypeDefault
side"top" | "bottom""bottom"
align"start" | "end""end"

BubbleGroup

Renders a div: a vertical Stack whose only layout prop is gap. It takes no align, so set that on each Bubble.

PropTypeDefault
gapSpacingStep1

MessageContext

The context a Message provides to the bubbles in it: the message's align. It is declared here, beside the bubble that reads it, and exported for message.tsx. A bubble outside a message reads null and works on its own.

bubbleStyles

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

KeyWhat it is
baseThe bubble's column, its fit width and its 80% cap
alignsOne entry per align, for the bubble and its content
fullWidthLifts the width cap, as a ghost bubble does
contentThe surface's padding, radius, type, border and focus ring
variantsThe surface's fill and text colour, one entry per variant
reactionsThe reaction chip: card fill, hairline, pill shape
reactionSidesThe chip's edge, one entry per side
reactionAlignsThe chip's corner, one entry per align
textInsetThe inline padding that lines text up with a bubble's text

Data attributes

AttributeOnEffect
data-slot="bubble"the rootTargets the bubble from a parent
data-variantthe rootReflects variant
data-alignthe rootReflects the resolved align
data-slot="bubble-content"the contentTargets the surface from a parent
data-slot="bubble-reactions"the reactionsTargets the chip from a parent
data-side, data-alignthe reactionsReflect side and align
data-slot="bubble-group"the groupTargets the group from a parent