Bubble

Displays conversational content in a message bubble. Supports variants, alignment, grouping, reactions, and collapsible content.

Hey there! what's up?

Hey! Want to see chat bubbles?

I can group messages, switch sides, and keep the whole thread easy to scan.

Sure. Hit me with your best demo.

Yes. You are reading a demo that is demoing itself. Very meta. Very on-brand.

1
import {
2
  Bubble,
3
  BubbleContent,
4
  BubbleGroup,
5
  BubbleReactions,
6
} from "@/components/features/pxl/conversation/bubble";
7
import { Emoji } from "@/components/ui/pxl/emoji";
8

9
export default function BubbleDemo() {
10
  return (
11
    <div className="flex w-full max-w-sm flex-col gap-8">
12
      <Bubble align="end">
13
        <BubbleContent>Hey there! what&apos;s up?</BubbleContent>
14
      </Bubble>
15
      <BubbleGroup>
16
        <Bubble variant="muted">
17
          <BubbleContent>Hey! Want to see chat bubbles?</BubbleContent>
18
        </Bubble>
19
        <Bubble variant="muted">
20
          <BubbleContent>
21
            I can group messages, switch sides, and keep the whole thread easy
22
            to scan.
23
          </BubbleContent>
24
          <BubbleReactions role="img" aria-label="Reaction: thumbs up">
25
            <Emoji as="span">👍</Emoji>
26
          </BubbleReactions>
27
        </Bubble>
28
      </BubbleGroup>
29
      <Bubble align="end">
30
        <BubbleContent>Sure. Hit me with your best demo.</BubbleContent>
31
      </Bubble>
32
      <Bubble variant="muted">
33
        <BubbleContent>
34
          Yes. You are reading a demo that is demoing itself. Very meta. Very
35
          on-brand.
36
        </BubbleContent>
37
        <BubbleReactions
38
          role="img"
39
          aria-label="Reactions: thumbs up, fire, eyes, and 2 more"
40
        >
41
          <Emoji as="span">👍</Emoji>
42
          <Emoji as="span">🔥</Emoji>
43
          <Emoji as="span">👀</Emoji>
44
          <span>+2</span>
45
        </BubbleReactions>
46
      </Bubble>
47
    </div>
48
  );
49
}

pnpm dlx shadcn@latest add pxl-ui/registry/conversation/bubble

Copy and paste the following code into your project.

1
import { mergeProps } from "@base-ui/react/merge-props";
2
import { useRender } from "@base-ui/react/use-render";
3
import { cva, type VariantProps } from "class-variance-authority";
4
import type { ComponentProps } from "react";
5

6
import { cn } from "@/lib/utils";
7

8
function BubbleGroup({ className, ...props }: ComponentProps<"div">) {
9
  return (
10
    <div
11
      data-slot="bubble-group"
12
      className={cn("flex min-w-0 flex-col gap-2", className)}
13
      {...props}
14
    />
15
  );
16
}
17

18
const bubbleVariants = cva(
19
  "group/bubble relative flex w-fit max-w-[80%] min-w-0 flex-col gap-1 group-data-[align=end]/message:self-end data-[align=end]:self-end data-[variant=ghost]:max-w-full",
20
  {
21
    variants: {
22
      variant: {
23
        default:
24
          "*:data-[slot=bubble-content]:bg-primary *:data-[slot=bubble-content]:text-primary-foreground [&>[data-slot=bubble-content]:is(button,a):hover]:bg-primary/80",
25
        secondary:
26
          "*:data-[slot=bubble-content]:bg-secondary *:data-[slot=bubble-content]:text-secondary-foreground [&>[data-slot=bubble-content]:is(button,a):hover]:bg-[color-mix(in_oklch,var(--secondary),var(--foreground)_5%)]",
27
        muted:
28
          "*:data-[slot=bubble-content]:bg-muted [&>[data-slot=bubble-content]:is(button,a):hover]:bg-[color-mix(in_oklch,var(--muted),var(--foreground)_5%)]",
29
        tinted:
30
          "*:data-[slot=bubble-content]:bg-[oklch(from_var(--primary)_0.93_calc(c*0.4)_h)] *:data-[slot=bubble-content]:text-foreground dark:*:data-[slot=bubble-content]:bg-[oklch(from_var(--primary)_0.3_calc(c*0.4)_h)] [&>[data-slot=bubble-content]:is(button,a):hover]:bg-[oklch(from_var(--primary)_0.88_calc(c*0.5)_h)] dark:[&>[data-slot=bubble-content]:is(button,a):hover]:bg-[oklch(from_var(--primary)_0.35_calc(c*0.5)_h)]",
31
        outline:
32
          "*:data-[slot=bubble-content]:border-border *:data-[slot=bubble-content]:bg-background [&>[data-slot=bubble-content]:is(button,a):hover]:bg-muted [&>[data-slot=bubble-content]:is(button,a):hover]:text-foreground dark:[&>[data-slot=bubble-content]:is(button,a):hover]:bg-input/30",
33
        ghost:
34
          "border-none *:data-[slot=bubble-content]:rounded-none *:data-[slot=bubble-content]:bg-transparent *:data-[slot=bubble-content]:p-0 [&>[data-slot=bubble-content]:is(button,a):hover]:bg-muted [&>[data-slot=bubble-content]:is(button,a):hover]:text-foreground dark:[&>[data-slot=bubble-content]:is(button,a):hover]:bg-muted/50",
35
        destructive:
36
          "*:data-[slot=bubble-content]:bg-destructive/10 *:data-[slot=bubble-content]:text-destructive dark:*:data-[slot=bubble-content]:bg-destructive/20 [&>[data-slot=bubble-content]:is(button,a):hover]:bg-destructive/20 dark:[&>[data-slot=bubble-content]:is(button,a):hover]:bg-destructive/30",
37
      },
38
    },
39
    defaultVariants: {
40
      variant: "default",
41
    },
42
  },
43
);
44

45
function Bubble({
46
  variant = "default",
47
  align = "start",
48
  className,
49
  ...props
50
}: ComponentProps<"div"> &
51
  VariantProps<typeof bubbleVariants> & {
52
    align?: "start" | "end";
53
  }) {
54
  return (
55
    <div
56
      data-slot="bubble"
57
      data-variant={variant}
58
      data-align={align}
59
      className={cn(bubbleVariants({ variant }), className)}
60
      {...props}
61
    />
62
  );
63
}
64

65
function BubbleContent({
66
  className,
67
  render,
68
  ...props
69
}: useRender.ComponentProps<"div">) {
70
  return useRender({
71
    defaultTagName: "div",
72
    props: mergeProps<"div">(
73
      {
74
        className: cn(
75
          "w-fit max-w-full min-w-0 overflow-hidden pixel-rounded pixel-size-lg px-3 py-2.5 text-sm leading-relaxed wrap-break-word group-data-[align=end]/bubble:self-end [button]:text-left [button,a]:transition-colors [button,a]:outline-none [button,a]:focus-visible:border-ring [button,a]:focus-visible:ring-3 [button,a]:focus-visible:ring-ring/30",
76
          className,
77
        ),
78
      },
79
      props,
80
    ),
81
    render,
82
    state: {
83
      slot: "bubble-content",
84
    },
85
  });
86
}
87

88
const bubbleReactionsVariants = cva(
89
  "absolute z-10 flex w-fit shrink-0 items-center justify-center gap-1 pixel-border pixel-color-white pixel-size-lg bg-muted px-[calc(var(--pixel-size)+(--spacing(1.5)))] py-[calc(var(--pixel-size)+(--spacing(0.5)))] text-sm ring-3 ring-card has-[button]:p-0",
90
  {
91
    variants: {
92
      side: {
93
        top: "top-0 -translate-y-3/4",
94
        bottom: "bottom-0 translate-y-3/4",
95
      },
96
      align: {
97
        start: "left-3",
98
        end: "right-3",
99
      },
100
    },
101
    defaultVariants: {
102
      side: "bottom",
103
      align: "end",
104
    },
105
  },
106
);
107

108
function BubbleReactions({
109
  side = "bottom",
110
  align = "end",
111
  className,
112
  ...props
113
}: ComponentProps<"div"> & {
114
  align?: "start" | "end";
115
  side?: "top" | "bottom";
116
}) {
117
  return (
118
    <div
119
      data-slot="bubble-reactions"
120
      data-align={align}
121
      data-side={side}
122
      className={cn(bubbleReactionsVariants({ side, align }), className)}
123
      {...props}
124
    />
125
  );
126
}
127

128
export { Bubble, BubbleContent, BubbleGroup, BubbleReactions };

Update the import paths to match your project setup.

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.

Usage

import {
  Bubble,
  BubbleContent,
  BubbleReactions
} from "@/components/features/pxl/conversation/bubble"

<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:

Bubble
├── BubbleContent
└── BubbleReactions

Use BubbleGroup to group consecutive bubbles from the same sender:

BubbleGroup
├── 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 render for link and button bubbles
Customizable styling through the className prop on every part

Variants

Use variant to change the visual treatment of the bubble.

Variant	Description
`default`	A strong primary bubble, usually for the current user.
`secondary`	The standard neutral bubble for conversation content.
`muted`	A lower-emphasis bubble for quiet supporting content.
`tinted`	A subtle primary-tinted bubble.
`outline`	A bordered bubble for secondary or rich content.
`ghost`	Unframed content for assistant text or rich content.
`destructive`	A destructive bubble for error or failed actions.

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.

align	Description
`start`	Align the bubble to the start of the conversation.
`end`	Align the bubble to the end of the conversation.

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.

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

Links and Buttons

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

import { Bubble, BubbleContent } from "@/components/features/pxl/chats/bubble"

export function BubbleLinkDemo() {
  return (
    <Bubble variant="muted">
      <BubbleContent render={<button />}>Click here</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.

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.

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

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

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.

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

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

<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 render 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.

<Bubble variant="muted" align="end">
  <BubbleContent render={<button type="button" onClick={onReply} />}>
    I forgot my password
  </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.

Prop	Type	Default	Description
`variant`	`"default" \| "secondary" \| "muted" \| "tinted" \| "outline" \| "ghost" \| "destructive"`	`"default"`	The bubble visual treatment.
`align`	`"start" \| "end"`	`"start"`	The inline alignment of the bubble.
`className`	`string`	-	Additional classes to apply to the root element.

BubbleContent

The bubble content wrapper.

Prop	Type	Default	Description
`render`	`ReactElement \| function`	-	Render the content as a different element such as a link.
`className`	`string`	-	Additional classes to apply to the content element.

BubbleReactions

Displays overlapped reactions for a bubble.

Prop	Type	Default	Description
`side`	`"top" \| "bottom"`	`"bottom"`	The side of the bubble to anchor the reactions.
`align`	`"start" \| "end"`	`"end"`	The inline alignment of the reactions.
`className`	`string`	-	Additional classes to apply to the reaction row.

BubbleGroup

Groups consecutive bubbles from the same sender.

Prop	Type	Default	Description
`className`	`string`	-	Additional classes to apply to the group root.