Bubble

import {
  Bubble,
  BubbleContent,

The Bubble component displays framed conversational content. Use it for chat text, short structured output, quoted replies, suggestions, and reactions.

For full-featured chat interfaces, use the Message component. Bubble is intentionally scoped to the bubble surface. Place avatars, names, timestamps, metadata, and message-level actions in Message.

Installation#

pnpmnpmyarnbun
pnpm dlx shadcn@latest add bubble
Copy

Usage#

Copyimport { Bubble, BubbleContent, BubbleReactions } from "@/components/ui/bubble"

Copy<Bubble>
  <BubbleContent>
    I checked the registry output and removed the stale route.
  </BubbleContent>
  <BubbleReactions>
    <span>👍</span>
  </BubbleReactions>
</Bubble>

Composition#

Use the following composition to build a bubble:

CopyBubble
├── BubbleContent
└── BubbleReactions

Use BubbleGroup to group consecutive bubbles from the same sender:

CopyBubbleGroup
├── Bubble
│   └── BubbleContent
└── Bubble
    └── BubbleContent

Features#

• Seven visual variants, from a strong primary bubble to unframed ghost content
• Start and end alignment for sender and receiver bubbles
• Reactions that anchor to the bubble edge with configurable side and alignment
• Bubbles size to their content, up to 80% of the container width
• Polymorphic content via asChild for link and button bubbles
• Customizable styling through the className prop on every part

Examples#

Variants#

Use variant to change the visual treatment of the bubble.

import { Markdown } from "@/components/markdown"
import {
  Bubble,

A bubble sizes to its content, up to 80% of the container width. The ghost variant removes the max-width so assistant text and rich content can span the full row.

Alignment#

Use align on Bubble to align the bubble to the start or end of the conversation.

import { Bubble, BubbleContent } from "@/components/ui/bubble"

export function BubbleAlignmentDemo() {

Note: When building chat interfaces, you probably want to use alignment on the Message component itself, not the Bubble component. You can use the role prop on the Message component to automatically align the bubble to the start or end of the conversation.

Bubble Group#

Use BubbleGroup to group consecutive bubbles from the same sender. Note the align prop should be set on the Bubble component itself, not the BubbleGroup component.

CopyBubbleGroup
├── Bubble
│   └── BubbleContent
└── Bubble
    └── BubbleContent

import {
  Bubble,
  BubbleContent,

Links and Buttons#

You can turn a bubble into a link or button by using the asChild prop on BubbleContent.

"use client"

import { toast } from "sonner"

Copyimport { Bubble, BubbleContent } from "@/components/ui/bubble"
 
export function BubbleLinkDemo() {
  return (
    <Bubble variant="muted">
      <BubbleContent asChild>
        <button>Click here</button>
      </BubbleContent>
    </Bubble>
  )
}

Reactions#

Use BubbleReactions for bubble reactions. You can use it to display reactions or quick action buttons. Use side and align to position the row — side="top" anchors it to the upper edge. Reactions overlap the bubble edge, so leave vertical space between rows — the examples below use a larger gap for this reason.

"use client"

import { toast } from "sonner"

Show More / Collapsible#

Long bubble content can be composed with Collapsible to allow for a show more or show less interaction. Use the CollapsibleTrigger component to trigger the collapsible content.

"use client"

import * as React from "react"

Tooltip#

Wrap a bubble in a Tooltip to reveal metadata on hover, such as when a message was read.

import { CheckIcon } from "lucide-react"

import {

Popover#

Pair a bubble with a Popover to surface more information on demand, such as the full error message for a failed action.

import { InfoIcon } from "lucide-react"

import {

Accessibility#

Bubble renders the presentational message surface. Keep conversation-level semantics on the surrounding container and follow the guidelines below.

Labeling Reactions#

Reactions render as a row of emoji. A screen reader reads each glyph with no context, and counters like +8 are announced as "plus eight". Group the row as a single image with a descriptive aria-label so it announces once. role="img" also hides the individual emoji from assistive tech, so no aria-hidden is needed.

Copy<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 instead and give icon-only buttons an aria-label.

Copy<BubbleReactions>
  <Button aria-label="Thumbs up" variant="secondary" size="icon-xs">
    <ThumbsUpIcon />
  </Button>
</BubbleReactions>

Interactive Bubbles#

When a bubble is clickable, render it as a real <button> or <a> with the asChild prop so it is focusable and exposes the correct role. BubbleContent ships a visible focus ring for interactive elements, and the accessible name comes from the bubble text. No extra label is needed.

Copy<Bubble variant="muted" align="end">
  <BubbleContent asChild>
    <button type="button" onClick={onReply}>
      I forgot my password
    </button>
  </BubbleContent>
</Bubble>

Meaning Beyond Color#

Bubble variants signal role and tone with color. Pair them with text, alignment, or icons so meaning is not conveyed by color alone. For a destructive bubble, keep the error context in the message text rather than relying on the color treatment.

API Reference#

Bubble#

The root bubble wrapper.

BubbleContent#

The bubble content wrapper.

BubbleReactions#

Displays overlapped reactions for a bubble.

BubbleGroup#

Groups consecutive bubbles from the same sender.