💌 Info

Version 2.0.0 removed the built-in Typewriter component. For Markdown rendering functionality, please use x-markdown-vue

Introduction

Bubble is a chat bubble component, commonly used in chat scenarios. It can display conversation content, supports custom avatars, headers, content, footers, and has loading state display.

Code Examples

Basic Usage

hello world !

Basic Usage

Simplest integration method.

<script setup lang="ts">
const content = ref('hello world !');
</script>

<template>
  <Bubble :content="content" />
</template>

Avatar and Placement

Good morning, how are you?

What a beautiful day!

Hi, good morning, I'm fine!

Hi, good morning, I'm fine! Thank you!

Support for Position and Avatar, and Spacing Settings

Set custom avatar through #avatar. Set position through placement property, provides start, end two option values.

💡 Tip

😸 Built-in element-plus el-avatar component. But to avoid property name conflicts, for example: el-avatar and Bubble's shape property. You need to use the following properties to set

1. Properties

• avatar Set avatar placeholder image
• avatar-size Set avatar placeholder size 👉This property is number type in el-avatar component, note that in this component it's string type for better custom style properties😊
• avatar-gap Set distance between avatar and bubble
• avatar-shape Set avatar shape
• avatar-icon Set avatar placeholder icon
• avatar-src-set Set avatar image srcset attribute
• avatar-alt Set avatar image alt attribute
• avatar-fit Set avatar placeholder image fill mode

2. Events

• @avatar-error Triggered when avatar loading fails.

<script setup lang="ts">
const avatarAI =
  'https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png';
const avatarUser = 'https://avatars.githubusercontent.com/u/76239030?v=4';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <!-- Avatar and Placement Left -->
    <Bubble
      content="Good morning, how are you?"
      placement="start"
      :avatar="avatarAI"
      avatar-size="48px"
    />

    <!-- avatar-size Set avatar placeholder space -->
    <Bubble
      content="What a beautiful day!"
      placement="start"
      avatar-size="48px"
    />

    <!-- Avatar and Placement Right -->
    <Bubble content="Hi, good morning, I'm fine!" placement="end">
      <template #avatar>
        <el-avatar :size="32" :src="avatarUser" />
      </template>
    </Bubble>

    <!-- avatar-gap property controls distance between bubble and avatar -->
    <Bubble
      content="Hi, good morning, I'm fine! Thank you!"
      placement="end"
      avatar-size="0px"
      avatar-gap="0px"
    />
  </div>
</template>

Header and Footer

Element Plus X

Hi! Hello, welcome to Element Plus X, if you have any questions, feel free to ask me~

Support for Custom Bubble Header and Footer Content

Customize bubble header and footer through #header and #footer slots.

<script setup lang="ts">
import { DocumentCopy, Refresh, Search, Star } from '@element-plus/icons-vue';

const content = ref(
  'Hi! Hello, welcome to Element Plus X, if you have any questions, feel free to ask me~'
);
const avatarAI =
  'https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png';
</script>

<template>
  <Bubble :content="content">
    <template #avatar>
      <el-avatar :src="avatarAI" />
    </template>
    <template #header>
      <span>Element Plus X</span>
    </template>
    <template #footer>
      <div class="footer-container">
        <el-button type="info" :icon="Refresh" size="small" circle />
        <el-button type="success" :icon="Search" size="small" circle />
        <el-button type="warning" :icon="Star" size="small" circle />
        <el-button color="#626aef" :icon="DocumentCopy" size="small" circle />
      </div>
    </template>
  </Bubble>
</template>

<style scoped lang="less">
.footer-container {
  :deep(.el-button + .el-button) {
    margin-left: 8px;
  }
}
</style>

Loading State

loading...

Thank you for using Element-Plus-X 🌹 Please wait...

State:

Loading State

Set loading state through loading property. Supports custom loading state content display through #loading slot.

💌 Info

#loading slot has higher priority, built-in loading styles will be disabled. But the loading property can still control the loading state.

<script setup lang="ts">
const loading = ref(true);
const content = ref('hello world !');
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 10px">
    <Bubble :content="content" :loading="loading" />

    <Bubble :content="content" :loading="loading">
      <template #loading>
        <div>loading...</div>
      </template>
    </Bubble>

    <Bubble :content="content" :loading="loading">
      <template #loading>
        <div>Thank you for using Element-Plus-X 🌹 Please wait...</div>
      </template>
    </Bubble>

    <div style="display: flex; align-items: center">
      <span>State: </span>
      <el-switch v-model="loading" />
    </div>
  </div>
</template>

Custom Content

😊 Welcome to element-plus-x, I'm a custom bubble

Recommended Content Custom Bubble

🥤 How to rest effectively after long hours of work?

💌 What's the secret to maintaining a positive mindset?

🔥 How to stay calm under tremendous pressure?

Customize Bubble Content

Customize bubble content through #content slot.

💌 Info

#content slot has higher priority, content property will be disabled. no-padding property can disable bubble content padding.

<script setup lang="ts">
const avatarSize = '48px';
const avatarAI =
  'https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <Bubble
      content="Welcome to element-plus-x."
      typing
      :avatar="avatarAI"
      :avatar-size="avatarSize"
      no-style
    >
      <template #content>
        <div class="content-container">
          😊 Welcome to element-plus-x, I'm a custom bubble
        </div>
      </template>
    </Bubble>

    <Bubble :avatar-size="avatarSize" typing no-style variant="borderless">
      <template #header>
        <div class="content-container-header">
          Recommended Content Custom Bubble
        </div>
      </template>
      <template #content>
        <div class="content-borderless-container">
          🥤 How to rest effectively after long hours of work?
        </div>
      </template>
    </Bubble>

    <Bubble :avatar-size="avatarSize" typing no-style variant="borderless">
      <template #content>
        <div class="content-borderless-container">
          💌 What's the secret to maintaining a positive mindset?
        </div>
      </template>
    </Bubble>

    <Bubble :avatar-size="avatarSize" typing no-style variant="borderless">
      <template #content>
        <div class="content-borderless-container">
          🔥 How to stay calm under tremendous pressure?
        </div>
      </template>
    </Bubble>
  </div>
</template>

<style scoped>
.content-container {
  padding: 12px;
  background-color: #f5f7fa;
  border-radius: 4px;
}

.content-container-header {
  font-size: 12px;
  color: #909399;
}

.content-borderless-container {
  user-select: none;
  padding: 12px;
  cursor: pointer;
  transition: background-color 0.3s;
  &:hover {
    background-color: #ebeef5;
  }
}
</style>

Variants and Shapes

filled

filled + round

filled + corner

borderless

borderless + round

borderless + corner

outlined

outlined + round

outlined + corner

shadow

shadow + round

shadow + corner

round

corner

placement end

Built-in Style Formats and Shapes

Set bubble's built-in style format through variant property. Set bubble's shape through shape property. Of course you can also combine them and use them together.

💌 Info

By default, variant is filled, shape is round.

When shape is corner, placement="end" will automatically flip the bubble so that the top-right corner radius pointer points to the user.

<script setup lang="ts"></script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <div style="display: flex; gap: 12px; align-items: center">
      <Bubble content="filled" variant="filled" />
      <Bubble content="filled + round" variant="filled" shape="round" />
      <Bubble content="filled + corner" variant="filled" shape="corner" />
    </div>

    <div style="display: flex; gap: 12px; align-items: center">
      <Bubble content="borderless" variant="borderless" />
      <Bubble content="borderless + round" variant="borderless" shape="round" />
      <Bubble
        content="borderless + corner"
        variant="borderless"
        shape="corner"
      />
    </div>

    <div style="display: flex; gap: 12px; align-items: center">
      <Bubble content="outlined" variant="outlined" />
      <Bubble content="outlined + round" variant="outlined" shape="round" />
      <Bubble content="outlined + corner" variant="outlined" shape="corner" />
    </div>

    <div style="display: flex; gap: 12px; align-items: center">
      <Bubble content="shadow" variant="shadow" />
      <Bubble content="shadow + round" variant="shadow" shape="round" />
      <Bubble content="shadow + corner" variant="shadow" shape="corner" />
    </div>

    <div style="display: flex; gap: 12px; align-items: center">
      <Bubble content="round" shape="round" />
    </div>

    <div style="display: flex; gap: 12px; align-items: center">
      <Bubble content="corner" shape="corner" />
      <Bubble content="placement end" shape="corner" placement="end" />
    </div>
  </div>
</template>

Theme Overrides (themeOverrides)

Override Bubble theme tokens via ConfigProvider.themeOverrides. See the full token list and template:

• Theme Tokens
• /theme-overrides.template.ts

When enabled, bubble content becomes narrower.

Start bubble: gradient background, larger radius and stronger shadow after overrides.

End bubble: use themeOverrides to build a consistent glass-like theme.

Theme Overrides (themeOverrides)

Override Bubble theme tokens via ConfigProvider.themeOverrides (background, border, radius, padding, width, etc.) for a clear before/after contrast.

<script setup lang="ts">
import { computed, ref } from 'vue';

const enabled = ref(true);

const themeOverrides = computed(() => {
  if (!enabled.value) return {};
  return {
    common: {
      'color-primary': '#8b5cf6',
      'border-color': 'rgba(139, 92, 246, 0.35)',
      'fill-color': 'rgba(139, 92, 246, 0.10)',
      'text-color-primary': 'rgba(15, 23, 42, 0.92)',
      'box-shadow': '0 18px 54px rgba(139, 92, 246, 0.22)'
    },
    components: {
      Bubble: {
        'bubble-content-max-width': '420px',
        'bubble-bg':
          'linear-gradient(135deg, rgba(139, 92, 246, 0.16), rgba(59, 130, 246, 0.10))',
        'bubble-border-color': 'rgba(139, 92, 246, 0.32)',
        'bubble-text-color': 'rgba(15, 23, 42, 0.86)',
        'bubble-radius': '18px',
        'bubble-padding-y': '14px',
        'bubble-padding-x': '18px',
        'bubble-shadow': '0 18px 52px rgba(139, 92, 246, 0.18)',
        'bubble-dot-color': '#8b5cf6'
      }
    }
  };
});
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <div
      style="display: flex; align-items: center; justify-content: space-between"
    >
      <div>When enabled, bubble content becomes narrower.</div>
      <button
        type="button"
        style="
          padding: 6px 10px;
          border-radius: 8px;
          border: 1px solid rgba(0, 0, 0, 0.12);
          background: rgba(0, 0, 0, 0.02);
          cursor: pointer;
        "
        @click="enabled = !enabled"
      >
        {{ enabled ? 'Disable theme overrides' : 'Enable theme overrides' }}
      </button>
    </div>

    <ConfigProvider apply-to="self" :theme-overrides="themeOverrides">
      <div
        style="
          padding: 14px;
          border-radius: 16px;
          border: 1px solid var(--elx-border-color);
          background:
            radial-gradient(
              1200px 280px at 0% 0%,
              rgba(139, 92, 246, 0.22),
              transparent 60%
            ),
            radial-gradient(
              900px 240px at 100% 20%,
              rgba(59, 130, 246, 0.14),
              transparent 55%
            ),
            rgba(0, 0, 0, 0.02);
          box-shadow: var(--elx-box-shadow);
          display: flex;
          flex-direction: column;
          gap: 10px;
        "
      >
        <Bubble
          placement="start"
          variant="borderless"
          content="Start bubble: gradient background, larger radius and stronger shadow after overrides."
        />
        <Bubble
          placement="end"
          variant="shadow"
          content="End bubble: use themeOverrides to build a consistent glass-like theme."
        />
        <Bubble placement="start" variant="shadow" loading />
      </div>
    </ConfigProvider>
  </div>
</template>

Using with x-markdown-vue

Starting from v2.0.0, the Typewriter component has been removed. For Markdown rendering functionality, please use x-markdown-vue or see the dedicated page: XMarkdown.

Installation

pnpm add x-markdown-vue
pnpm add katex
pnpm add shiki shiki-stream

💡 Tip

If you need code block syntax highlighting, please install shiki and shiki-stream. Otherwise, you may see this error in the console: Streaming highlighter initialization failed: Error: Failed to load shiki-stream module

Full Demo

Basic Usage (Supports formulas, code blocks, task lists)

Streaming Rendering

Use enable-animate property to achieve typewriter effect, simulating AI streaming output

Using with x-markdown-vue

Supports formulas, code blocks, task lists, and streaming rendering.

<script setup lang="ts">
import 'katex/dist/katex.min.css';

import 'shiki';
import 'shiki-stream';

const MarkdownRenderer = shallowRef();
onMounted(async () => {
  if (typeof window === 'undefined') return;
  await import('x-markdown-vue/style');
  const mod = await import('x-markdown-vue');
  MarkdownRenderer.value = mod.MarkdownRenderer ?? mod.default ?? mod;
});

const avatar = 'https://avatars.githubusercontent.com/u/76239030?s=40&v=4';

const staticContent = ref(`### Inline Formulas
1. Euler's formula: $e^{i\\pi} + 1 = 0$
2. Quadratic formula: $x = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}$
3. Vector dot product: $\\vec{a} \\cdot \\vec{b} = a_x b_x + a_y b_y + a_z b_z$

### [] Wrapped Formula
\\[ e^{i\\pi} + 1 = 0 \\]

\\[\\boxed{boxed content}\\]

### Block Formulas
1. Fourier Transform:
$$
F(\\omega) = \\int_{-\\infty}^{\\infty} f(t) e^{-i\\omega t} dt
$$

2. Matrix Multiplication:
$$
\\begin{bmatrix}
a & b \\\\
c & d
\\end{bmatrix}
\\begin{bmatrix}
x \\\\
y
\\end{bmatrix}
=
\\begin{bmatrix}
ax + by \\\\
cx + dy
\\end{bmatrix}
$$

3. Taylor Series:
$$
f(x) = \\sum_{n=0}^{\\infty} \\frac{f^{(n)}(a)}{n!} (x - a)^n
$$

### Task List & Code Block
- [x] Add some task
- [ ] Do some task

\`\`\`typescript
const greeting: string = "Hello World";
console.log(greeting);
\`\`\`
`);

const streamingContent = ref('');
let interval: ReturnType<typeof setInterval>;

function startStreaming() {
  streamingContent.value = '';
  const text = `# Title
This is a Markdown example.
- List item 1
- List item 2
**Bold text** and *italic text*

- [x] Add some task
- [ ] Do some task

\`\`\`typescript
const greeting = "Hello World";
console.log(greeting);
\`\`\`
`;
  let index = 0;
  interval = setInterval(() => {
    if (index < text.length) {
      streamingContent.value += text[index];
      index++;
    } else {
      clearInterval(interval);
    }
  }, 30);
}

function stopStreaming() {
  clearInterval(interval);
}

function resetStreaming() {
  stopStreaming();
  streamingContent.value = '';
}

onUnmounted(() => {
  clearInterval(interval);
});
</script>

<template>
  <div class="markdown-demo-container">
    <div class="demo-section">
      <div class="demo-title">
        Basic Usage (Supports formulas, code blocks, task lists)
      </div>
      <Bubble :avatar="avatar" placement="start">
        <template #content>
          <div class="markdown-content-wrapper">
            <component
              :is="MarkdownRenderer"
              v-if="MarkdownRenderer"
              :markdown="staticContent"
            />
          </div>
        </template>
      </Bubble>
    </div>

    <div class="demo-section">
      <div class="demo-title">Streaming Rendering</div>
      <p class="demo-tip">
        Use <code>enable-animate</code> property to achieve typewriter effect,
        simulating AI streaming output
      </p>
      <div class="btn-list">
        <el-button type="primary" @click="startStreaming">
          Start Streaming
        </el-button>
        <el-button @click="stopStreaming"> Stop </el-button>
        <el-button @click="resetStreaming"> Reset </el-button>
      </div>
      <Bubble :avatar="avatar" placement="start">
        <template #content>
          <div class="markdown-content-wrapper">
            <component
              :is="MarkdownRenderer"
              v-if="MarkdownRenderer"
              :markdown="streamingContent"
              :enable-animate="true"
            />
          </div>
        </template>
      </Bubble>
    </div>
  </div>
</template>

<style scoped lang="scss">
.markdown-demo-container {
  .demo-section {
    margin-bottom: 24px;

    &:last-child {
      margin-bottom: 0;
    }
  }

  .demo-title {
    font-weight: 600;
    margin-bottom: 12px;
    color: var(--vp-c-text-1);
  }

  .demo-tip {
    color: var(--vp-c-text-2);
    font-size: 14px;
    margin-bottom: 12px;

    code {
      background: var(--vp-c-default-soft);
      padding: 2px 6px;
      border-radius: 4px;
    }
  }

  .btn-list {
    display: flex;
    gap: 12px;
    margin-bottom: 16px;
  }
}

.markdown-content-wrapper {
  word-break: break-word;
  color: #24292e;

  :deep(h1),
  :deep(h2),
  :deep(h3),
  :deep(h4),
  :deep(h5),
  :deep(h6) {
    margin-top: 16px;
    margin-bottom: 8px;
    font-weight: 600;
    line-height: 1.25;
    &:first-child {
      margin-top: 0;
    }
  }

  :deep(p) {
    margin-top: 0;
    margin-bottom: 8px;
    line-height: 1.6;
    &:last-child {
      margin-bottom: 0;
    }
  }

  :deep(ul),
  :deep(ol) {
    padding-left: 20px;
    margin-top: 0;
    margin-bottom: 8px;

    ul,
    ol {
      margin-top: 4px;
      margin-bottom: 0;
    }
  }

  :deep(ul) {
    list-style-type: disc;
  }

  :deep(ol) {
    list-style-type: decimal;
  }

  :deep(li) {
    margin: 4px 0;
    line-height: 1.6;

    &.task-list-item {
      list-style-type: none;
      padding-left: 0;
      display: flex;
      align-items: flex-start;
      margin-left: -20px;

      input[type='checkbox'] {
        margin: 5px 8px 0 0;
        flex-shrink: 0;
      }
    }
  }

  :deep(a) {
    color: #0366d6;
    text-decoration: none;
    &:hover {
      text-decoration: underline;
    }
  }

  :deep(code):not(pre code) {
    background-color: rgba(27, 31, 35, 0.05);
    padding: 0.2em 0.4em;
    border-radius: 3px;
    font-family:
      ui-monospace,
      SFMono-Regular,
      SF Mono,
      Menlo,
      Consolas,
      Liberation Mono,
      monospace;
    font-size: 85%;
  }

  :deep(blockquote) {
    padding: 0 1em;
    color: #6a737d;
    border-left: 0.25em solid #dfe2e5;
    margin: 0 0 8px 0;
  }

  :deep(hr) {
    height: 0.25em;
    padding: 0;
    margin: 16px 0;
    background-color: #e1e4e8;
    border: 0;
  }

  :deep(table) {
    display: block;
    width: 100%;
    overflow: auto;
    margin-top: 0;
    margin-bottom: 16px;
    border-collapse: collapse;

    th,
    td {
      padding: 6px 13px;
      border: 1px solid #dfe2e5;
    }

    tr {
      background-color: #fff;
      border-top: 1px solid #c6cbd1;
      &:nth-child(2n) {
        background-color: #f6f8fa;
      }
    }
  }
}

:deep(.x-md-code-block) {
  pre {
    background-color: #f6f8fa !important;
    padding: 16px;
    border-radius: 8px;
    overflow: auto;

    code {
      font-family:
        ui-monospace,
        SFMono-Regular,
        SF Mono,
        Menlo,
        Consolas,
        Liberation Mono,
        monospace;
      font-size: 14px;
      line-height: 1.5;

      .line {
        display: block;
        min-height: 1rem;
      }
    }
  }
}

:deep(.x-md-animated-word) {
  animation: fadeIn 0.2s ease-in-out forwards;
  display: inline-block;
}

@keyframes fadeIn {
  from {
    opacity: 0;
    transform: translateY(2px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}
</style>

Basic Usage

<template>
  <Bubble :avatar="avatar" placement="start">
    <template #content>
      <MarkdownRenderer :markdown="content" />
    </template>
  </Bubble>
</template>

<script setup>
import { ref } from 'vue';
import { MarkdownRenderer } from 'x-markdown-vue';
import 'x-markdown-vue/style';

const avatar = ref('https://example.com/avatar.png');
const content = ref('**Hello** World!\n\nThis is **Markdown** content');
</script>

Streaming Rendering (Alternative to Typing Effect)

<template>
  <Bubble :avatar="avatar" placement="start">
    <template #content>
      <MarkdownRenderer :markdown="content" :enable-animate="true" />
    </template>
  </Bubble>
</template>

<script setup>
import { ref } from 'vue';
import { MarkdownRenderer } from 'x-markdown-vue';
import 'x-markdown-vue/style';

const content = ref('');
</script>

Properties

Property Name	Type	Default	Description
content	String	''	Text content to display inside the bubble
placement	String	'start'	Bubble position, options are 'start' or 'end', representing left and right sides respectively.
avatar	String	''	Image URL for the bubble avatar
loading	Boolean	false	Whether to show loading state. When true, loading state will be displayed inside the bubble.
shape	String	null	Bubble shape, options are 'round' (rounded corners) or 'corner' (angular).
variant	String	'filled'	Bubble style variant, options are 'filled' (filled), 'borderless' (no border), 'outlined' (outline), 'shadow' (shadow).
noStyle	Boolean	false	Whether to remove styles, when true, removes built-in padding and background color from the bubble
maxWidth	String	'500px'	Maximum width of bubble content.
avatar-size	String	''	Set avatar placeholder size
avatar-gap	String	'12px'	Set gap value between avatar and bubble
avatar-shape	String	''	Avatar shape, options are 'circle' (circular) or 'square' (square).
avatar-icon	String	''	Avatar icon, priority higher than avatar, supports passing icon names like 'user'.
avatar-src-set	String	''	Set avatar image srcset attribute
avatar-alt	String	''	Set avatar image alt attribute
avatar-fit	String	'cover'	Set avatar image object-fit attribute, options: 'cover', 'contain', 'fill', 'none', 'scale-down'

Events

Event Name	Parameters	Type	Description
@avatarError	ref instance	Function	Triggered when avatar loading fails

Ref Instance Methods

Property Name	Type	Description
restart	Function	Restart.
destroy	Function	Actively destroy Bubble component.

Slots

Slot Name	Parameters	Type	Description
#avatar	-	Slot	Custom avatar display content
#header	-	Slot	Custom bubble top display content
#content	-	Slot	Custom bubble display content
#loading	-	Slot	Custom bubble loading state display content
#footer	-	Slot	Custom bubble bottom display content

Features

1. Layout Direction - Supports left alignment (start) and right alignment (end)
2. Content Types - Supports plain text, custom slot content
3. Loading State - Built-in loading animation, supports custom loading content
4. Visual Effects - Provides multiple shapes and variants (rounded/angular corners, filled/outlined/shadow, etc.)
5. Flexible Slots - Provides avatar, header, content, footer, loading state and other slots