Bubble
The surface for one piece of a conversation, with variants, alignment, groups, reactions and collapsible content.
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
Needs the arene setup first. Also adds Stack.
Install the packages it imports:
Set up the token layer and the StyleX compiler, if you have not already. See
Installation, and paste states.ts from the same page,
which is where an interactive bubble's focus ring comes from. BubbleGroup is
a Stack, so paste that first.
Paste this source into the file named in its title.
Change the @/ imports if your project uses different aliases.
Usage
Composition
Use BubbleGroup for consecutive bubbles from the same sender:
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.
| Variant | Use |
|---|---|
default | The primary fill, usually for the current user |
secondary | The neutral fill, usually for the other side |
outline | A hairline edge and no fill, for options and links |
ghost | No fill and no edge, for assistant text and rich output |
destructive | A 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.
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.
Links and buttons
Pass render to BubbleContent to make the bubble a link or a button. It
then takes a hover step and shows a focus ring.
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.
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.
The contrast check found two text colours that fall below 4.5:1 on the muted background.
Tooltip
Place a Tooltip in the reactions for details that appear on hover, such as the time a message was read.
Popover
Pair a bubble with a Popover to show more detail on demand, such as the full error behind a failed action.
Rich content
A ghost bubble holds paragraphs, lists and inline code with no frame around
them. Render your markdown output inside BubbleContent.
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.
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.
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.
| Prop | Type | Default |
|---|---|---|
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.
| Prop | Type | Default |
|---|---|---|
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.
| Prop | Type | Default |
|---|---|---|
gap | SpacingStep | 1 |
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.
| Key | What it is |
|---|---|
base | The bubble's column, its fit width and its 80% cap |
aligns | One entry per align, for the bubble and its content |
fullWidth | Lifts the width cap, as a ghost bubble does |
content | The surface's padding, radius, type, border and focus ring |
variants | The surface's fill and text colour, one entry per variant |
reactions | The reaction chip: card fill, hairline, pill shape |
reactionSides | The chip's edge, one entry per side |
reactionAligns | The chip's corner, one entry per align |
textInset | The inline padding that lines text up with a bubble's text |
Data attributes
| Attribute | On | Effect |
|---|---|---|
data-slot="bubble" | the root | Targets the bubble from a parent |
data-variant | the root | Reflects variant |
data-align | the root | Reflects the resolved align |
data-slot="bubble-content" | the content | Targets the surface from a parent |
data-slot="bubble-reactions" | the reactions | Targets the chip from a parent |
data-side, data-align | the reactions | Reflect side and align |
data-slot="bubble-group" | the group | Targets the group from a parent |