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.

👍🔥👀+2

<script setup lang="ts">
import { Bubble, BubbleContent, BubbleGroup, BubbleReactions } from '@/components/ui/bubble'
</script>

<template>
  <div class="flex w-full max-w-sm flex-col gap-8 py-12">
    <Bubble align="end">
      <BubbleContent>Hey there! what&apos;s up?</BubbleContent>
    </Bubble>
    <BubbleGroup>
      <Bubble variant="muted">
        <BubbleContent>Hey! Want to see chat bubbles?</BubbleContent>
      </Bubble>
      <Bubble variant="muted">
        <BubbleContent>
          I can group messages, switch sides, and keep the whole thread easy
          to scan.
        </BubbleContent>
        <BubbleReactions role="img" aria-label="Reaction: thumbs up">
          <span>👍</span>
        </BubbleReactions>
      </Bubble>
    </BubbleGroup>
    <Bubble align="end">
      <BubbleContent>Sure. Hit me with your best demo.</BubbleContent>
    </Bubble>
    <Bubble variant="muted">
      <BubbleContent>
        Yes. You are reading a demo that is demoing itself. Very meta. Very
        on-brand.
      </BubbleContent>
      <BubbleReactions
        role="img"
        aria-label="Reactions: thumbs up, fire, eyes, and 2 more"
      >
        <span>👍</span>
        <span>🔥</span>
        <span>👀</span>
        <span>+2</span>
      </BubbleReactions>
    </Bubble>
  </div>
</template>

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.

Installation


pnpm dlx shadcn-vue@latest add bubble

Usage

<script setup lang="ts">
import { Bubble, BubbleContent, BubbleReactions } from '@/components/ui/bubble'
</script>

<template>
  <Bubble>
    <BubbleContent>
      I checked the registry output and removed the stale route.
    </BubbleContent>
    <BubbleReactions>
      <span>👍</span>
    </BubbleReactions>
  </Bubble>
</template>

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 as or as-child for link and button bubbles
Customizable styling through the class prop on every part

Examples

Variants

Use variant to change the visual treatment of the bubble.

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.

<script setup lang="ts">
import { Bubble, BubbleContent, BubbleReactions } from '@/components/ui/bubble'
</script>

<template>
  <div class="flex w-full max-w-sm flex-col gap-12 py-12">
    <Bubble>
      <BubbleContent>This is the default primary bubble.</BubbleContent>
    </Bubble>
    <Bubble variant="secondary" align="end">
      <BubbleContent>This is the secondary variant.</BubbleContent>
    </Bubble>
    <Bubble variant="muted">
      <BubbleContent>
        This one is muted. It uses a lower emphasis color for the chat bubble.
      </BubbleContent>
      <BubbleReactions role="img" aria-label="Reaction: thumbs up">
        <span>👍</span>
      </BubbleReactions>
    </Bubble>
    <Bubble variant="tinted" align="end">
      <BubbleContent>
        This one is tinted. The tint is a softer color derived from the
        primary color.
      </BubbleContent>
    </Bubble>
    <Bubble variant="outline">
      <BubbleContent>We can also use an outlined variant.</BubbleContent>
    </Bubble>
    <Bubble variant="destructive" align="end">
      <BubbleContent>Or a destructive variant with a reaction.</BubbleContent>
      <BubbleReactions role="img" aria-label="Reaction: fire">
        <span>🔥</span>
      </BubbleReactions>
    </Bubble>
    <Bubble variant="ghost">
      <BubbleContent>
        Ghost bubbles work for assistant text, <b>markdown</b>, 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>code</code> in it.

        Ghost bubbles are full width and can take the full width of the container.
      </BubbleContent>
    </Bubble>
  </div>
</template>

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.

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

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

<script setup lang="ts">
import { Bubble, BubbleContent } from '@/components/ui/bubble'
</script>

<template>
  <div class="flex w-full max-w-sm flex-col gap-8 py-12">
    <Bubble variant="muted">
      <BubbleContent>
        This bubble is aligned to the start. This is the default alignment.
      </BubbleContent>
    </Bubble>
    <Bubble align="end">
      <BubbleContent>
        This bubble is aligned to the end. Use this for user messages.
      </BubbleContent>
    </Bubble>
  </div>
</template>

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 set align on the Message component itself. Bubbles inside MessageContent automatically follow the message alignment.

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

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.

<script setup lang="ts">
import { Bubble, BubbleContent, BubbleGroup, BubbleReactions } from '@/components/ui/bubble'
</script>

<template>
  <div class="flex w-full max-w-sm flex-col gap-8 py-12">
    <Bubble variant="muted">
      <BubbleContent>Can you tell me what&apos;s the issue?</BubbleContent>
    </Bubble>
    <BubbleGroup>
      <Bubble align="end">
        <BubbleContent>You tell me!</BubbleContent>
      </Bubble>
      <Bubble align="end">
        <BubbleContent>It worked yesterday. You broke it!</BubbleContent>
      </Bubble>
      <Bubble align="end">
        <BubbleContent>Find the bug and fix it.</BubbleContent>
        <BubbleReactions aria-label="Reactions: eyes" align="start">
          <span>👀</span>
        </BubbleReactions>
      </Bubble>
    </BubbleGroup>
    <Bubble variant="muted">
      <BubbleContent>
        Want me to diff yesterday&apos;s you against today&apos;s you?
        It&apos;s a bit embarrassing.
      </BubbleContent>
    </Bubble>
  </div>
</template>

Links and Buttons

Use as-child to merge BubbleContent styling and attributes onto a link or button passed through its default slot.

How can I help you today?

<script setup lang="ts">
import { toast } from 'vue-sonner'
import { Bubble, BubbleContent, BubbleGroup } from '@/components/ui/bubble'
</script>

<template>
  <div class="flex w-full max-w-sm flex-col gap-8 py-12">
    <Bubble variant="muted">
      <BubbleContent>How can I help you today?</BubbleContent>
    </Bubble>
    <BubbleGroup>
      <Bubble variant="tinted" align="end">
        <BubbleContent as-child>
          <button type="button" @click="() => toast('You clicked forgot password')">
            I forgot my password
          </button>
        </BubbleContent>
      </Bubble>
      <Bubble variant="tinted" align="end">
        <BubbleContent as-child>
          <button type="button" @click="() => toast('You clicked help with subscription')">
            I need help with my subscription
          </button>
        </BubbleContent>
      </Bubble>
      <Bubble variant="tinted" align="end">
        <BubbleContent as-child>
          <button
            type="button"
            @click="() =>
              toast('You clicked something else. Talk to a human.')"
          >
            Something else. Talk to a human.
          </button>
        </BubbleContent>
      </Bubble>
    </BubbleGroup>
  </div>
</template>

<script setup lang="ts">
import { Bubble, BubbleContent } from '@/components/ui/bubble'
</script>

<template>
  <Bubble variant="muted">
    <BubbleContent as-child>
      <button type="button">Click here</button>
    </BubbleContent>
  </Bubble>
</template>

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.

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?

<script setup lang="ts">
import { toast } from 'vue-sonner'
import { Bubble, BubbleContent, BubbleReactions } from '@/components/ui/bubble'
import { Button } from '@/components/ui/button'
</script>

<template>
  <div class="flex w-full max-w-sm flex-col gap-12 py-12">
    <Bubble variant="muted" align="end">
      <BubbleContent>
        I don&apos;t need tests, I know my code works.
      </BubbleContent>
      <BubbleReactions
        align="start"
        role="img"
        aria-label="Reactions: thumbs up, surprised"
      >
        <span>👍</span>
        <span>😮</span>
      </BubbleReactions>
    </Bubble>
    <Bubble variant="muted">
      <BubbleContent>
        Bold. Fine I&apos;ll add some tests. I&apos;ll let you know when
        they&apos;re done.
      </BubbleContent>
      <BubbleReactions
        role="img"
        aria-label="Reactions: eyes, rocket, and 2 more"
      >
        <span>👀</span>
        <span>🚀</span>
        <span>+2</span>
      </BubbleReactions>
    </Bubble>
    <Bubble variant="default" align="end">
      <BubbleContent>
        Tests passed on the first try. All 142 of them. Looking good!
      </BubbleContent>
      <BubbleReactions
        side="top"
        align="start"
        role="img"
        aria-label="Reactions: party popper, clapping hands"
      >
        <span>🎉</span>
        <span>👏</span>
      </BubbleReactions>
    </Bubble>
    <Bubble variant="destructive">
      <BubbleContent>Are you sure I can run this command?</BubbleContent>
      <BubbleReactions>
        <Button
          variant="ghost"
          size="sm"
          @click="() => toast.success('You clicked yes, running command...')"
        >
          Yes, run it
        </Button>
      </BubbleReactions>
    </Bubble>
  </div>
</template>

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.

How can I help you today?

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

<script setup lang="ts">
import { ChevronDownIcon } from '@lucide/vue'
import { computed, ref } from 'vue'
import { Bubble, BubbleContent } from '@/components/ui/bubble'
import { Button } from '@/components/ui/button'
import { Collapsible, CollapsibleTrigger } from '@/components/ui/collapsible'

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
const open = ref(false)
const preview = computed(() => `${text.slice(0, previewLength)}...`)
const isLong = computed(() => text.length > previewLength)
</script>

<template>
  <div class="flex w-full max-w-sm flex-col gap-8 py-12">
    <Bubble variant="muted">
      <BubbleContent>How can I help you today?</BubbleContent>
    </Bubble>

    <Bubble variant="muted" align="end">
      <BubbleContent class="whitespace-pre-line">
        <Collapsible v-model:open="open">
          <div>{{ (open || !isLong) ? text : preview }}</div>
          <template v-if="isLong">
            <CollapsibleTrigger as-child>
              <Button variant="link" class="group/collapsible gap-1 p-0 text-muted-foreground">
                {{ open ? "Show less" : "Show more" }}
                <ChevronDownIcon
                  data-icon="inline-end"
                  class="group-data-[state=open]/collapsible:rotate-180 size-4"
                />
              </Button>
            </CollapsibleTrigger>
          </template>
        </Collapsible>
      </BubbleContent>
    </Bubble>
  </div>
</template>

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

Did you remove the stale route?

Yes, removed it from the registry.

<script setup lang="ts">
import { CheckIcon } from '@lucide/vue'
import { Bubble, BubbleContent, BubbleReactions } from '@/components/ui/bubble'
import { Button } from '@/components/ui/button'
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
</script>

<template>
  <div class="flex w-full max-w-sm flex-col gap-4 py-12">
    <Bubble variant="secondary">
      <BubbleContent>Did you remove the stale route?</BubbleContent>
    </Bubble>
    <Bubble align="end">
      <BubbleContent>Yes, removed it from the registry.</BubbleContent>
      <BubbleReactions>
        <Tooltip>
          <TooltipTrigger as-child>
            <Button variant="ghost" size="icon-sm" class="rounded-full">
              <CheckIcon />
            </Button>
          </TooltipTrigger>
          <TooltipContent>Read on Jan 5, 2026 at 4:32 PM</TooltipContent>
        </Tooltip>
      </BubbleReactions>
    </Bubble>
  </div>
</template>

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

Run the build script.

Failed to run the command.

<script setup lang="ts">
import { InfoIcon } from '@lucide/vue'
import { Bubble, BubbleContent, BubbleReactions } from '@/components/ui/bubble'
import { Button } from '@/components/ui/button'
import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
</script>

<template>
  <div class="flex w-full max-w-sm flex-col gap-4 py-12">
    <Bubble align="end">
      <BubbleContent>Run the build script.</BubbleContent>
    </Bubble>
    <Bubble variant="destructive">
      <BubbleContent>Failed to run the command.</BubbleContent>
      <BubbleReactions>
        <Popover>
          <PopoverTrigger as-child>
            <Button variant="ghost" size="icon-sm" aria-label="Show error details" class="aria-expanded:text-destructive rounded-full">
              <InfoIcon />
            </Button>
          </PopoverTrigger>
          <PopoverContent>
            <div class="flex flex-col gap-1 text-sm">
              <div class="text-sm font-medium">
                Command failed with exit code 1
              </div>
              <div class="text-sm text-muted-foreground">
                ENOENT: no such file or directory, open pnpm-lock.yaml
              </div>
            </div>
          </PopoverContent>
        </Popover>
      </BubbleReactions>
    </Bubble>
  </div>
</template>

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">
  <span>👍</span>
  <span>🔥</span>
  <span>+8</span>
</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, pass a real <button> or <a> through BubbleContent with as-child 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 as-child>
    <button type="button" @click="onReply">
      I forgot my password
    </button>
  </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

All Bubble parts render a <div> by default. Use as to choose another element, or as-child to merge the component's attributes and styles onto the single element or component in its default slot.

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.
`as`	`string \| Component`	`"div"`	The element or component to render.
`as-child`	`boolean`	`false`	Render the default slot as the root and merge props onto it.
`class`	`string`	-	Additional classes to apply to the root element.

BubbleContent

The bubble content wrapper.

Prop	Type	Default	Description
`as`	`string \| Component`	`"div"`	The element or component to render.
`as-child`	`boolean`	`false`	Render the default slot as the root and merge props onto it.
`class`	`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.
`as`	`string \| Component`	`"div"`	The element or component to render.
`as-child`	`boolean`	`false`	Render the default slot as the root and merge props onto it.
`class`	`string`	-	Additional classes to apply to the reaction row.

BubbleGroup

Groups consecutive bubbles from the same sender.

Prop	Type	Default	Description
`as`	`string \| Component`	`"div"`	The element or component to render.
`as-child`	`boolean`	`false`	Render the default slot as the root and merge props onto it.
`class`	`string`	-	Additional classes to apply to the group root.

Breadcrumb Button