Bubble

Display conversation content with message bubbles, reactions, and optional actions.

  1. You:

    Hey there! what’s up?

  2. Assistant:

    Hey! Want to see chat bubbles?

  3. Assistant:

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

    👍
  4. You:

    Sure. Hit me with your best demo.

  5. Assistant:

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

    👍🔥👀+2

Usage

With a Basecoat style bundle loaded, add .bubble to a <div>. Its first child is the content; an optional second <div> holds reactions. The root class does not require a particular HTML element. Use .bubble-group for closely spaced bubbles. No Bubble JavaScript is required.

<div class="bubble">
  <p>I checked the registry output and removed the stale route.</p>
  <div role="img" aria-label="Reaction: thumbs up">
    <span>👍</span>
  </div>
</div>

Bubbles size to their content, up to 80% of their container. Put them in a column flex layout so data-align="end" can align outgoing messages. Leave room between messages for overlapping reactions.

The conversation examples use an ordered list with one <li> per message. Sender labels use sr-only to preserve upstream’s appearance while identifying who spoke. Keep the list’s role="list" so Safari exposes its semantics when Tailwind removes list markers. The static previews do not announce updates.

These examples use upstream’s blue theme through local CSS variables. Omit those variables to use your application’s theme. Avatars, sender names, timestamps, and message-level controls belong outside the bubble.

Examples

Variants

Use data-variant="secondary", muted, tinted, outline, ghost, or destructive. The default uses your primary color. Ghost removes the frame and allows full-width content.

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.

Alignment

Alignment follows the document direction. The default is start; add data-align="end" for outgoing messages.

This bubble is aligned to the start. This is the default alignment.

This bubble is aligned to the end. Use this for user messages.

Bubble group

Use .bubble-group for closely spaced messages. In a conversation list, keep each message in its own <li> and add spacing when the sender changes. Set alignment on each bubble.

  1. Assistant:

    Can you tell me what’s the issue?

  2. You:

    You tell me!

  3. You:

    It worked yesterday. You broke it!

  4. You:

    Find the bug and fix it.

    👀
  5. Assistant:

    Want me to diff yesterday’s you against today’s you? It’s a bit embarrassing.

Use an <a href="..."> or <button type="button"> as the content child. The whole surface becomes interactive, with a keyboard focus indicator.

This example uses Toast. Include Basecoat’s runtime and Toast script (or all.min.js), and one #toaster container per page.

  1. Assistant:

    How can I help you today?

    <div class="bubble" data-variant="tinted">
      <a href="/installation">Read the installation guide</a>
    </div>

    Reactions

    Reactions default to the bottom end edge. Use data-side="top" or data-align="start" on the second <div> to move them. Reuse Button for actions. The action below shares the Toast setup from the previous example.

    1. You:

      I don’t need tests, I know my code works.

      👍😮
    2. Assistant:

      Bold. Fine I’ll add some tests. I’ll let you know when they’re done.

      👀🚀+2
    3. You:

      Tests passed on the first try. All 142 of them. Looking good!

      🎉👏
    4. Assistant:

      Are you sure I can run this command?

    Show more

    Use native <details> for optional expansion. The preview is hidden while the disclosure is open; no script or content animation is needed. Browsers supporting ::details-content place the trigger below the expanded text. Older browsers retain the native trigger-first order.

    1. Assistant:

      How can I help you today?

    2. You:

      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 control…

      Show more

      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.

    Tooltip

    Reuse Tooltip on a reaction button. Its accessible label also exposes the read receipt without needing to hover.

    1. Assistant:

      Did you remove the stale route?

    2. You:

      Yes, removed it from the registry.

    Popover

    Reuse Popover for error details. Include Basecoat’s runtime and Popover script, or the full JavaScript bundle. This inline popover uses a narrower width on small screens.

    1. You:

      Run the build script.

    2. Assistant:

      Failed to run the command.

    RTL

    Set dir="rtl" on the conversation. Message and reaction alignment use the inline start and end edges.

    1. أنت:

      مرحباً! كيف حالك؟

    2. المساعد:

      أهلاً! هل تريد مشاهدة فقاعات المحادثة؟

      👍

    Chat log

    Use an <ol> for chronological messages and one <li> per message. Keep the sender, timestamp, bubble, and any attachment list inside that message. An <article> is optional when the complete message makes sense as a standalone contribution; Bubble itself does not require it.

    1. Alice ·

      Have you reviewed the updated document?

    2. Bob ·

      Yes, the changes look good.

    For a live conversation, put the list inside a named role="log" wrapper. This chat-log pattern announces new messages politely without moving focus. Keep the list role on the <ol>; do not replace it with log.

    <div role="log" aria-label="Conversation">
      <ol role="list">
        <li>
          <p>Alice · <time datetime="2026-11-07T18:18:00+08:00">18:18</time></p>
          <div class="bubble">
            <p>Here is the updated document.</p>
          </div>
        </li>
      </ol>
    </div>

    Create the live-region wrapper before appending new messages. For streamed replies, batch announcements rather than announcing each token. A static transcript only needs the list, as in the preview above.