For manual installation, copy each of the source codes below in their respective locations.
components/core/core.py
components/ui/bubble.py
Displays conversational content in a message bubble. Supports variants, alignment, grouping, reactions, and collapsible content.
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.
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 class_name prop on every part
Examples
Variants
Use variant to change the visual treatment of the bubble.
Props used:variant on bubble.root.
This is the default primary bubble.
This is the secondary variant.
This one is muted. It uses a lower emphasis color for the chat bubble.
👍
This one is tinted. The tint is a softer color derived from the primary color.
We can also use an outlined variant.
Or a destructive variant with a reaction.
🔥
Ghost bubbles work for assistant text, **markdown**, and other content that should not be framed.
This is perfect for assistant messages that should not have a frame and can take the full width of the container. You can also render `code` in it.
Ghost bubbles are full width and can take the full width of the container.
import reflex as rx
from components.ui.bubble import bubble
def bubble_with_variants():
return rx.el.div(
bubble.root(
bubble.content("This is the default primary bubble."),
variant="default",
),
bubble.root(
bubble.content("This is the secondary variant."),
variant="secondary",
align="end",
),
bubble.root(
bubble.content(
"This one is muted. It uses a lower emphasis color for the chat bubble."
),
bubble.reactions(
rx.el.span("👍"),
role="img",
aria_label="Reaction: thumbs up",
),
variant="muted",
),
bubble.root(
bubble.content(
"This one is tinted. The tint is a softer color derived from the primary color."
),
variant="tinted",
align="end",
),
bubble.root(
bubble.content("We can also use an outlined variant."),
variant="outline",
),
bubble.root(
bubble.content("Or a destructive variant with a reaction."),
bubble.reactions(
rx.el.span("🔥"),
role="img",
aria_label="Reaction: fire",
),
variant="destructive",
align="end",
),
bubble.root(
bubble.content(
rx.html(
"""
Ghost bubbles work for assistant text, **markdown**, and other content that should not be framed.
This is perfect for assistant messages that should not have a frame and can take the full width of the container. You can also render `code` in it.
Ghost bubbles are full width and can take the full width of the container.
""",
class_name="docs-prose"
),
),
variant="ghost",
),
class_name="flex w-full max-w-sm flex-col gap-12 py-12",
)
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.root to align the bubble to the start or end of the conversation.
Props used:align on bubble.root.
This bubble is aligned to the start. This is the default alignment.
This bubble is aligned to the end. Use this for user messages.
import reflex as rx
from components.ui.bubble import bubble
def bubble_alignment_demo():
return rx.el.div(
bubble.root(
bubble.content(
"This bubble is aligned to the start. This is the default alignment."
),
variant="muted",
align="start",
),
bubble.root(
bubble.content(
"This bubble is aligned to the end. Use this for user messages."
),
align="end",
),
class_name="flex w-full max-w-sm flex-col gap-8 py-12",
)
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.root component to automatically align the bubble to the start or end of the conversation.
Bubble Group
Use bubble.group to group consecutive bubbles from the same sender. Note the align prop should be set on the bubble.root component itself, not the bubble.group component.
Props used:align on bubble.root (set per-bubble, not on bubble.group).
Can you tell me what's the issue?
You tell me!
It worked yesterday. You broke it!
Find the bug and fix it.
👀
Want me to diff yesterday's you against today's you? It's a bit embarrassing.
import reflex as rx
from components.ui.bubble import bubble
def bubble_group_demo():
return rx.el.div(
bubble.root(
bubble.content("Can you tell me what's the issue?"),
variant="muted",
),
bubble.group(
bubble.root(
bubble.content("You tell me!"),
align="end",
),
bubble.root(
bubble.content("It worked yesterday. You broke it!"),
align="end",
),
bubble.root(
bubble.content("Find the bug and fix it."),
bubble.reactions(
rx.el.span("👀"),
aria_label="Reactions: eyes",
align="start",
),
align="end",
),
),
bubble.root(
bubble.content(
"Want me to diff yesterday's you against today's you? "
"It's a bit embarrassing."
),
variant="muted",
),
class_name="flex w-full max-w-sm flex-col gap-8 py-12",
)
Links and Buttons
You can turn a bubble into a link or button by using the passing the interactive elements directly into the bubble.content slot. The bubble.content accepts *children so simply placing a button or link will render that component.
Props used: none required — pass a button/rx.el.a as a child of bubble.content.
How can I help you today?
import reflex as rx
from components.ui.bubble import bubble
def bubble_link_button_demo():
return rx.el.div(
bubble.root(
bubble.content("How can I help you today?"),
variant="muted",
),
bubble.group(
bubble.root(
bubble.content(
rx.el.button(
"I forgot my password",
on_click=rx.toast("You clicked forgot password"),
class_name="w-full text-left",
)
),
variant="tinted",
align="end",
),
bubble.root(
bubble.content(
rx.el.button(
"I need help with my subscription",
on_click=rx.toast("You clicked help with subscription"),
class_name="w-full text-left",
)
),
variant="tinted",
align="end",
),
bubble.root(
bubble.content(
rx.el.button(
"Something else. Talk to a human.",
on_click=rx.toast(
"You clicked something else. Talk to a human."
),
class_name="w-full text-left",
)
),
variant="tinted",
align="end",
),
),
class_name="flex w-full max-w-sm flex-col gap-8 py-12",
)
Reactions
Use bubble.reactions 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.
Props used:side, align on bubble.reactions.
I don't need tests, I know my code works.
👍😮
Bold. Fine I'll add some tests. I'll let you know when they're done.
👀🚀+2
Tests passed on the first try. All 142 of them. Looking good!
🎉👏
Are you sure I can run this command?
import reflex as rx
from components.ui.bubble import bubble
def bubble_reactions_demo():
return rx.el.div(
bubble.root(
bubble.content("I don't need tests, I know my code works."),
bubble.reactions(
rx.el.span("👍"),
rx.el.span("😮"),
align="start",
role="img",
aria_label="Reactions: thumbs up, surprised",
),
variant="muted",
align="end",
),
bubble.root(
bubble.content(
"Bold. Fine I'll add some tests. I'll let you know when they're done."
),
bubble.reactions(
rx.el.span("👀"),
rx.el.span("🚀"),
rx.el.span("+2"),
role="img",
aria_label="Reactions: eyes, rocket, and 2 more",
),
variant="muted",
),
bubble.root(
bubble.content(
"Tests passed on the first try. All 142 of them. Looking good!"
),
bubble.reactions(
rx.el.span("🎉"),
rx.el.span("👏"),
side="top",
align="start",
role="img",
aria_label="Reactions: party popper, clapping hands",
),
variant="default",
align="end",
),
bubble.root(
bubble.content("Are you sure I can run this command?"),
bubble.reactions(
rx.el.button(
"Yes, run it",
on_click=rx.toast.success("You clicked yes, running command..."),
class_name="px-2 py-0.5 text-xs hover:bg-accent rounded-md",
),
),
variant="destructive",
),
class_name="flex w-full max-w-sm flex-col gap-12 py-12",
)
Accessibility
bubble.root 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.
When a bubble is clickable, render it as a real <button> or <a>. bubble.-* content accept *children so simply passing in the interactive component will get rendered. bubble.content ships a visible focus ring for interactive elements, and the accessible name comes from the bubble text. No extra label is needed.
bubble.root(
bubble.content(
"I forgot my password",
rx.el.button(type="button", on_click=on_reply)
),
variant="muted",
align="end"
)
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.