Displays conversational content in a message bubble. Supports variants, alignment, grouping, reactions, and collapsible content.
import { html } from '@webjsdev/core';
import {
bubbleGroupClass, bubbleClass, bubbleContentClass, bubbleReactionsClass,
} from '#components/ui/bubble.ts';
export default function BubbleDemo() {
return html`
<div class="flex w-full max-w-sm flex-col gap-8 py-12">
<div data-slot="bubble" data-variant="default" data-align="end" class=${bubbleClass()}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>Hey there! what's up?</div>
</div>
<div data-slot="bubble-group" class=${bubbleGroupClass()}>
<div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>Hey! Want to see chat bubbles?</div>
</div>
<div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>
I can group messages, switch sides, and keep the whole thread easy
to scan.
</div>
<div data-slot="bubble-reactions" data-align="end" data-side="bottom" role="img" aria-label="Reaction: thumbs up" class=${bubbleReactionsClass()}>
<span>👍</span>
</div>
</div>
</div>
<div data-slot="bubble" data-variant="default" data-align="end" class=${bubbleClass()}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>Sure. Hit me with your best demo.</div>
</div>
<div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>
Yes. You are reading a demo that is demoing itself. Very meta. Very
on-brand.
</div>
<div data-slot="bubble-reactions" data-align="end" data-side="bottom" role="img" aria-label="Reactions: thumbs up, fire, eyes, and 2 more" class=${bubbleReactionsClass()}>
<span>👍</span>
<span>🔥</span>
<span>👀</span>
<span>+2</span>
</div>
</div>
</div>
`;
}
View Code
The bubble helpers display framed conversational content. Use them for chat text, short structured output, quoted replies, suggestions, and reactions.
For full-featured chat interfaces, use the Message helpers. A bubble is intentionally scoped to the bubble surface. Place avatars, names, timestamps, metadata, and message-level actions in the Message.
Installation
Copy and paste the following code into your project.
/**
* Bubble: a chat speech bubble, the group that stacks several from one sender,
* and the emoji reactions pinned to its corner. Tier-1 class helper; pair with
* the message helpers for the row, avatar and header around it.
*
* shadcn parity:
* BubbleGroup → bubbleGroupClass()
* Bubble (variant: default | secondary | muted | tinted | outline | ghost | destructive)
* → bubbleClass({ variant }), alias bubbleVariants
* BubbleContent → bubbleContentClass()
* BubbleReactions (side: top | bottom, align: start | end)
* → bubbleReactionsClass({ side, align }), alias bubbleReactionsVariants
*
* The variant colours the content, so put `data-slot="bubble-content"` on the
* inner element and `data-variant` on the bubble. Inside a message with
* `data-align="end"` the bubble follows to the inline end.
*
* A11y (required for accessible output): the bubble is text inside a message,
* so it needs no role of its own. Reactions are buttons when they act (with an
* `aria-label` such as "2 people reacted with thumbs up", since an emoji alone
* reads poorly) and plain text when they only show a count.
*
* Design tokens used: --primary, --secondary, --muted, --accent, --border,
* --destructive.
*
* @example
* ```html
* <div class=${bubbleClass()} data-slot="bubble" data-variant="default">
* <div class=${bubbleContentClass()} data-slot="bubble-content">Shipping it now.</div>
* </div>
* ```
*/
import { cn } from '../lib/utils.ts';
/** Set `data-slot="bubble-group"` on the element. */
export function bubbleGroupClass(): string {
return 'gap-2 flex min-w-0 flex-col';
}
const BUBBLE_BASE =
'max-w-[80%] gap-1 group-data-[align=end]/message:self-end data-[align=end]:self-end data-[variant=ghost]:max-w-full group/bubble relative flex w-fit min-w-0 flex-col';
const BUBBLE_VARIANTS = {
default: '*:data-[slot=bubble-content]:bg-primary *:data-[slot=bubble-content]:text-primary-foreground [&>[data-slot=bubble-content]:is(button,a):hover]:bg-primary/80',
secondary: '*: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%)]',
muted: '*:data-[slot=bubble-content]:bg-muted [&>[data-slot=bubble-content]:is(button,a):hover]:bg-[color-mix(in_oklch,var(--muted),var(--foreground)_5%)]',
tinted: '*: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)]',
outline: '*: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',
ghost: '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',
destructive: '*: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',
} as const;
/** The part, with its variant options. Set its `data-slot` and any `data-variant` / `data-size` to match. */
export function bubbleClass(opts: { variant?: keyof typeof BUBBLE_VARIANTS } & { className?: string } = {}): string {
return cn(BUBBLE_BASE, BUBBLE_VARIANTS[opts.variant ?? 'default'], opts.className);
}
/**
* shadcn's name for {@link bubbleClass}, so shadcn code ports verbatim. Like cva,
* it merges a `className` into the result.
*/
export function bubbleVariants(opts: { variant?: keyof typeof BUBBLE_VARIANTS } & { className?: string } = {}): string {
return bubbleClass(opts);
}
/** Set `data-slot="bubble-content"` on the element. */
export function bubbleContentClass(): string {
return 'rounded-xl border border-transparent px-3 py-2 text-sm leading-relaxed group-data-[align=end]/bubble:self-end [button,a]:outline-none [button,a]:focus-visible:border-ring [button,a]:focus-visible:ring-3 [button,a]:focus-visible:ring-ring/50 w-fit max-w-full min-w-0 overflow-hidden wrap-break-word [button]:text-start [button,a]:transition-colors';
}
const BUBBLE_REACTIONS_BASE =
'shrink-0 gap-1 rounded-full bg-muted px-1.5 py-0.5 text-sm ring-3 ring-card has-[button]:p-0 absolute z-10 flex w-fit items-center justify-center';
const BUBBLE_REACTIONS_SIDES = {
top: 'top-0 -translate-y-3/4',
bottom: 'bottom-0 translate-y-3/4',
} as const;
const BUBBLE_REACTIONS_ALIGNS = {
start: 'start-3',
end: 'end-3',
} as const;
/** The part, with its variant options. Set its `data-slot` and any `data-variant` / `data-size` to match. */
export function bubbleReactionsClass(opts: { side?: keyof typeof BUBBLE_REACTIONS_SIDES; align?: keyof typeof BUBBLE_REACTIONS_ALIGNS } & { className?: string } = {}): string {
return cn(BUBBLE_REACTIONS_BASE, BUBBLE_REACTIONS_SIDES[opts.side ?? 'bottom'], BUBBLE_REACTIONS_ALIGNS[opts.align ?? 'end'], opts.className);
}
/**
* shadcn's name for {@link bubbleReactionsClass}, so shadcn code ports verbatim. Like cva,
* it merges a `className` into the result.
*/
export function bubbleReactionsVariants(opts: { side?: keyof typeof BUBBLE_REACTIONS_SIDES; align?: keyof typeof BUBBLE_REACTIONS_ALIGNS } & { className?: string } = {}): string {
return bubbleReactionsClass(opts);
}
Update the import paths to match your project setup.
Usage
import { bubbleClass, bubbleContentClass, bubbleReactionsClass } from '#components/ui/bubble.ts';
<div data-slot="bubble" data-variant="default" data-align="start" class=${bubbleClass()}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>
I checked the registry output and removed the stale route.
</div>
<div data-slot="bubble-reactions" data-side="bottom" data-align="end" class=${bubbleReactionsClass()}>
<span>��</span>
</div>
</div>
Composition
Use the following composition to build a bubble:
Bubble
├── BubbleContent
└── BubbleReactions
Each part is a plain element carrying its helper's classes and its data-slot. Use bubbleGroupClass() 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
- Link and button bubbles: the content helper goes straight on an
<a>or<button> - Customizable styling by merging your own classes into any part with
cn()
Variants
Use the variant option (with a matching data-variant) to change the visual treatment of the bubble.
import { html } from '@webjsdev/core';
import {
bubbleClass, bubbleContentClass, bubbleReactionsClass,
} from '#components/ui/bubble.ts';
export default function BubbleVariantsDemo() {
return html`
<div class="flex w-full max-w-sm flex-col gap-12 py-12">
<div data-slot="bubble" data-variant="default" data-align="start" class=${bubbleClass()}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>This is the default primary bubble.</div>
</div>
<div data-slot="bubble" data-variant="secondary" data-align="end" class=${bubbleClass({ variant: 'secondary' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>This is the secondary variant.</div>
</div>
<div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>
This one is muted. It uses a lower emphasis color for the chat bubble.
</div>
<div data-slot="bubble-reactions" data-side="bottom" data-align="end" role="img" aria-label="Reaction: thumbs up" class=${bubbleReactionsClass()}>
<span>👍</span>
</div>
</div>
<div data-slot="bubble" data-variant="tinted" data-align="end" class=${bubbleClass({ variant: 'tinted' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>
This one is tinted. The tint is a softer color derived from the
primary color.
</div>
</div>
<div data-slot="bubble" data-variant="outline" data-align="start" class=${bubbleClass({ variant: 'outline' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>We can also use an outlined variant.</div>
</div>
<div data-slot="bubble" data-variant="destructive" data-align="end" class=${bubbleClass({ variant: 'destructive' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>Or a destructive variant with a reaction.</div>
<div data-slot="bubble-reactions" data-side="bottom" data-align="end" role="img" aria-label="Reaction: fire" class=${bubbleReactionsClass()}>
<span>🔥</span>
</div>
</div>
<div data-slot="bubble" data-variant="ghost" data-align="start" class=${bubbleClass({ variant: 'ghost' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>
<div data-slot="markdown" class="w-full min-w-0 space-y-4 overflow-hidden">
<p>
Ghost bubbles work for assistant text, <strong>markdown</strong>,
and other content that should not be framed.
</p>
<p>
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 class="rounded-sm bg-muted px-1 py-0.5 font-mono text-[0.9em]">code</code> in it.
</p>
<p>Ghost bubbles are full width and can take the full width of the container.</p>
</div>
</div>
</div>
</div>
`;
}
View Code
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 data-align on the bubble to align it to the start or end of the conversation.
import { html } from '@webjsdev/core';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
export default function BubbleAlignmentDemo() {
return html`
<div class="flex w-full max-w-sm flex-col gap-8 py-12">
<div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>
This bubble is aligned to the start. This is the default alignment.
</div>
</div>
<div data-slot="bubble" data-variant="default" data-align="end" class=${bubbleClass()}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>
This bubble is aligned to the end. Use this for user messages.
</div>
</div>
</div>
`;
}
View Code
Note: When building chat interfaces, you probably want to set the alignment on the message itself, not the bubble. A bubble inside a message with data-align="end" follows it to the end of the conversation.
Bubble Group
Use bubbleGroupClass() to group consecutive bubbles from the same sender. Note the data-align attribute should be set on each bubble itself, not the group.
BubbleGroup
├── Bubble
│ └── BubbleContent
└── Bubble
└── BubbleContent
import { html } from '@webjsdev/core';
import {
bubbleGroupClass, bubbleClass, bubbleContentClass, bubbleReactionsClass,
} from '#components/ui/bubble.ts';
export default function BubbleGroupDemo() {
return html`
<div class="flex w-full max-w-sm flex-col gap-8 py-12">
<div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>Can you tell me what's the issue?</div>
</div>
<div data-slot="bubble-group" class=${bubbleGroupClass()}>
<div data-slot="bubble" data-variant="default" data-align="end" class=${bubbleClass()}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>You tell me!</div>
</div>
<div data-slot="bubble" data-variant="default" data-align="end" class=${bubbleClass()}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>It worked yesterday. You broke it!</div>
</div>
<div data-slot="bubble" data-variant="default" data-align="end" class=${bubbleClass()}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>Find the bug and fix it.</div>
<div data-slot="bubble-reactions" data-side="bottom" data-align="start" aria-label="Reactions: eyes" class=${bubbleReactionsClass({ align: 'start' })}>
<span>👀</span>
</div>
</div>
</div>
<div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>
Want me to diff yesterday's you against today's you?
It's a bit embarrassing.
</div>
</div>
</div>
`;
}
View Code
Links and Buttons
You can turn a bubble into a link or button by putting bubbleContentClass() on an <a> or <button> instead of a <div>.
import { html } from '@webjsdev/core';
import {
bubbleGroupClass, bubbleClass, bubbleContentClass,
} from '#components/ui/bubble.ts';
// The kit has no asChild: the content helper goes straight on the <button>
// (or an <a>). Wire each one's click to whatever it should do.
const reply = (text: string) => html`
<div data-slot="bubble" data-variant="tinted" data-align="end" class=${bubbleClass({ variant: 'tinted' })}>
<button type="button" data-slot="bubble-content" class=${bubbleContentClass()}>${text}</button>
</div>
`;
export default function BubbleLinkButtonDemo() {
return html`
<div class="flex w-full max-w-sm flex-col gap-8 py-12">
<div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>How can I help you today?</div>
</div>
<div data-slot="bubble-group" class=${bubbleGroupClass()}>
${reply('I forgot my password')}
${reply('I need help with my subscription')}
${reply('Something else. Talk to a human.')}
</div>
</div>
`;
}
View Code
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
export function BubbleLinkDemo() {
return html`
<div data-slot="bubble" data-variant="muted" class=${bubbleClass({ variant: 'muted' })}>
<button type="button" data-slot="bubble-content" class=${bubbleContentClass()}>Click here</button>
</div>
`;
}
Reactions
Use bubbleReactionsClass() for bubble reactions. You can use it to display reactions or quick action buttons. Use the side and align options (with matching data-side and data-align) to position the row, where 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.
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import {
bubbleClass, bubbleContentClass, bubbleReactionsClass,
} from '#components/ui/bubble.ts';
export default function BubbleReactionsDemo() {
return html`
<div class="flex w-full max-w-sm flex-col gap-12 py-12">
<div data-slot="bubble" data-variant="muted" data-align="end" class=${bubbleClass({ variant: 'muted' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>
I don't need tests, I know my code works.
</div>
<div data-slot="bubble-reactions" data-side="bottom" data-align="start" role="img" aria-label="Reactions: thumbs up, surprised" class=${bubbleReactionsClass({ align: 'start' })}>
<span>👍</span>
<span>😮</span>
</div>
</div>
<div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>
Bold. Fine I'll add some tests. I'll let you know when
they're done.
</div>
<div data-slot="bubble-reactions" data-side="bottom" data-align="end" role="img" aria-label="Reactions: eyes, rocket, and 2 more" class=${bubbleReactionsClass()}>
<span>👀</span>
<span>🚀</span>
<span>+2</span>
</div>
</div>
<div data-slot="bubble" data-variant="default" data-align="end" class=${bubbleClass()}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>
Tests passed on the first try. All 142 of them. Looking good!
</div>
<div data-slot="bubble-reactions" data-side="top" data-align="start" role="img" aria-label="Reactions: party popper, clapping hands" class=${bubbleReactionsClass({ side: 'top', align: 'start' })}>
<span>🎉</span>
<span>👏</span>
</div>
</div>
<div data-slot="bubble" data-variant="destructive" data-align="start" class=${bubbleClass({ variant: 'destructive' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>Are you sure I can run this command?</div>
<div data-slot="bubble-reactions" data-side="bottom" data-align="end" class=${bubbleReactionsClass()}>
<button type="button" data-slot="button" data-variant="ghost" data-size="xs" class=${buttonClass({ variant: 'ghost', size: 'xs' })}>Yes, run it</button>
</div>
</div>
</div>
`;
}
View Code
Show More / Collapsible
Long bubble content can be composed with a Collapsible to allow for a show more or show less interaction. The collapsible is a native <details>, so its <summary> is the trigger and the toggle needs no script.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { collapsibleClass, collapsibleTriggerClass } from '#components/ui/collapsible.ts';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
import { ChevronDownIcon } from '#lib/ui/lucide.ts';
const text = `The accessibility review found two focus states that were visually too subtle in dark mode.
I checked the dialog, menu, and drawer paths because each one renders focusable controls inside a layered surface.
The dialog and drawer are fine. The menu needs the hover and focus tokens split so keyboard focus stays visible when the pointer is not involved.
I also recommend keeping the change in the style file instead of the primitive so the other themes can choose their own focus treatment later.`;
const previewLength = 180;
// A native <details> is the collapsible, so it opens and closes with no
// script. The preview and the full text sit above it, and the wrapper's
// :has(details[open]) picks which one shows.
export default function BubbleCollapsible() {
const isLong = text.length > previewLength;
const preview = `${text.slice(0, previewLength)}...`;
return html`
<div class="flex w-full max-w-sm flex-col gap-8 py-12">
<div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>How can I help you today?</div>
</div>
<div data-slot="bubble" data-variant="muted" data-align="end" class=${bubbleClass({ variant: 'muted' })}>
<div data-slot="bubble-content" class=${cn(bubbleContentClass(), 'group/text')}>
${isLong
? html`
<div class="whitespace-pre-line group-has-[details[open]]/text:hidden">${preview}</div>
<div class="hidden whitespace-pre-line group-has-[details[open]]/text:block">${text}</div>
<details data-slot="collapsible" class=${collapsibleClass()}>
<summary data-slot="collapsible-trigger" class=${cn(collapsibleTriggerClass(), buttonClass({ variant: 'link' }), 'w-fit justify-start gap-1 p-0 text-muted-foreground')}>
<span class="group-open:hidden">Show more</span>
<span class="hidden group-open:inline">Show less</span>
${ChevronDownIcon('group-open:rotate-180')}
</summary>
</details>`
: html`<div class="whitespace-pre-line">${text}</div>`}
</div>
</div>
</div>
`;
}
View Code
Tooltip
Wrap a bubble's control in a Tooltip to reveal metadata on hover, such as when a message was read.
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
bubbleClass, bubbleContentClass, bubbleReactionsClass,
} from '#components/ui/bubble.ts';
import { CheckIcon } from '#lib/ui/lucide.ts';
export default function BubbleTooltipDemo() {
return html`
<div class="flex w-full max-w-sm flex-col gap-4 py-12">
<div data-slot="bubble" data-variant="secondary" data-align="start" class=${bubbleClass({ variant: 'secondary' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>Did you remove the stale route?</div>
</div>
<div data-slot="bubble" data-variant="default" data-align="end" class=${bubbleClass()}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>Yes, removed it from the registry.</div>
<div data-slot="bubble-reactions" data-side="bottom" data-align="end" class=${cn(bubbleReactionsClass(), 'p-0')}>
<ui-tooltip>
<ui-tooltip-trigger>
<button type="button" data-slot="button" data-variant="ghost" data-size="icon-xs" aria-label="Read receipt" class=${buttonClass({ variant: 'ghost', size: 'icon-xs' })}>
${CheckIcon()}
</button>
</ui-tooltip-trigger>
<ui-tooltip-content>Read on Jan 5, 2026 at 4:32 PM</ui-tooltip-content>
</ui-tooltip>
</div>
</div>
</div>
`;
}
View Code
Popover
Pair a bubble with a Popover to surface more information on demand, such as the full error message for a failed action.
Command failed with exit code 1
ENOENT: no such file or directory, open pnpm-lock.yaml
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
popoverContentClass, popoverHeaderClass, popoverTitleClass, popoverDescriptionClass,
} from '#components/ui/popover.ts';
import {
bubbleClass, bubbleContentClass, bubbleReactionsClass,
} from '#components/ui/bubble.ts';
import { InfoIcon } from '#lib/ui/lucide.ts';
export default function BubblePopoverDemo() {
return html`
<div class="flex w-full max-w-sm flex-col gap-4 py-12">
<div data-slot="bubble" data-variant="default" data-align="end" class=${bubbleClass()}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>Run the build script.</div>
</div>
<div data-slot="bubble" data-variant="destructive" data-align="start" class=${bubbleClass({ variant: 'destructive' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>Failed to run the command.</div>
<div data-slot="bubble-reactions" data-side="bottom" data-align="end" class=${bubbleReactionsClass()}>
<button type="button" popovertarget="bubble-popover-details" aria-haspopup="dialog" aria-label="Show error details" data-slot="button" data-variant="ghost" data-size="icon-xs" class=${cn(buttonClass({ variant: 'ghost', size: 'icon-xs' }), 'aria-expanded:text-destructive')}>
${InfoIcon()}
</button>
</div>
<div id="bubble-popover-details" popover role="dialog" aria-labelledby="bubble-popover-title" data-slot="popover-content" data-side="bottom" data-align="center" class=${popoverContentClass()}>
<div data-slot="popover-header" class=${popoverHeaderClass()}>
<h4 id="bubble-popover-title" data-slot="popover-title" class=${cn(popoverTitleClass(), 'text-sm')}>Command failed with exit code 1</h4>
<p data-slot="popover-description" class=${cn(popoverDescriptionClass(), 'text-sm')}>
ENOENT: no such file or directory, open pnpm-lock.yaml
</p>
</div>
</div>
</div>
</div>
`;
}
View Code
Accessibility
A 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.
<div data-slot="bubble-reactions" role="img" aria-label="Reactions: thumbs up, fire, and 8 more"
class=${bubbleReactionsClass()}>
<span>��</span>
<span>��</span>
<span>+8</span>
</div>
When reactions are interactive, render buttons instead and give icon-only buttons an aria-label.
<div data-slot="bubble-reactions" class=${bubbleReactionsClass()}>
<button type="button" aria-label="Thumbs up" class=${buttonClass({ variant: 'secondary', size: 'icon-xs' })}>
${ThumbsUpIcon()}
</button>
</div>
Interactive Bubbles
When a bubble is clickable, put the content helper on a real <button> or <a> so it is focusable and exposes the correct role. The content classes ship a visible focus ring for interactive elements, and the accessible name comes from the bubble text. No extra label is needed.
<div data-slot="bubble" data-variant="muted" data-align="end" class=${bubbleClass({ variant: 'muted' })}>
<button type="button" data-slot="bubble-content" class=${bubbleContentClass()} @click=${onReply}>
I forgot my password
</button>
</div>
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
Every part is a helper that returns classes for a plain element. Set the part's data-slot, and the data-variant, data-align and data-side attributes that match the options you pass, since the styles key on them.
bubbleClass
The root bubble wrapper, on data-slot="bubble". bubbleVariants() is an alias of bubbleClass() that also merges a className.
bubbleContentClass
The bubble content, on data-slot="bubble-content". Put it on a <div>, or on an <a> or <button> for an interactive bubble. It takes no options.
bubbleReactionsClass
Displays overlapped reactions for a bubble, on data-slot="bubble-reactions". bubbleReactionsVariants() is an alias of bubbleReactionsClass() that also merges a className.
bubbleGroupClass
Groups consecutive bubbles from the same sender, on data-slot="bubble-group". It takes no options.