📌 Warning

Added in version 1.1.6 Added scroll to bottom button, similar to Doubao🔥. Added scrollbar on mouse hover to enhance interaction experience. Please update and try it out.

🐵 This warm tip was last updated: 2025-04-13

💡 Tip

Note: The new version's auto-scroll will automatically scroll when the list length changes. However, after scrolling up, you need to manually call the scrollToBottom method to re-enable auto-scroll. Or, when the scrollbar reaches the bottom, auto-scroll will be triggered again.

The logic is the same as before, so you can upgrade without any worries.

Introduction

BubbleList relies on the Bubble component and is used to display a list of chat bubbles. This component supports setting the maximum list height and has an auto-scroll feature. It also provides various scroll control methods that users can easily call. It is powerful and requires no mental burden for developers.

Code Examples

Basic Usage

💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~

Hahaha, let me try

💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~

Hahaha, let me try

💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~

Basic Usage

Pre-styled bubble list, quickly create a chat record through a simple Array of messages.

📌 Warning

You can pass properties to the built-in Bubble component through the item property. Set properties for each bubble. More flexible usage. For specific properties, please refer to the Bubble component documentation.

All our message operations only need to maintain this array.

Including streaming message settings. Here we don't use interface streaming operations. In our template project, we go through real combat. You can use it as a reference.

👉 Template Project Preview

👉 Template Project Source Code Welcome to star🥰

You can also control the maximum height of the list through the max-height property.

<script setup lang="ts">
import type {
  BubbleListItemProps,
  BubbleListProps
} from 'vue-element-plus-x/types/BubbleList';

type listType = BubbleListItemProps & {
  key: number;
  role: 'user' | 'ai';
};

const list: BubbleListProps<listType>['list'] = generateFakeItems(5);

function generateFakeItems(count: number): listType[] {
  const messages: listType[] = [];
  for (let i = 0; i < count; i++) {
    const role = i % 2 === 0 ? 'ai' : 'user';
    const placement = role === 'ai' ? 'start' : 'end';
    const key = i + 1;
    const content =
      role === 'ai'
        ? '💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~'.repeat(
            5
          )
        : `Hahaha, let me try`;
    const loading = false;
    const shape = 'corner';
    const variant = role === 'ai' ? 'filled' : 'outlined';
    const avatar =
      role === 'ai'
        ? 'https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png'
        : 'https://avatars.githubusercontent.com/u/76239030?v=4';

    messages.push({
      key,
      role,
      placement,
      content,
      loading,
      shape,
      variant,
      avatar,
      avatarSize: '24px',
      avatarGap: '12px'
    });
  }
  return messages;
}
</script>

<template>
  <BubbleList :list="list" max-height="350px" />
</template>

Customized List

Dynamic content setting

Custom loading

Element Plus X 🍧

💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~

2:32 PM

🧁 User

Hahaha, let me try

2:33 PM

Element Plus X 🍧

💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~

2:32 PM

🧁 User

Hahaha, let me try

2:33 PM

Element Plus X 🍧

💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~

2:32 PM

Custom List Display

🍋 Through #avatar, #header, #content, #loading, #footer slots, you can more flexibly control the rendering of bubble lists

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

type listType = BubbleListItemProps & {
  key: number;
  role: 'user' | 'ai';
};

// Example call
const bubbleItems = ref<BubbleListProps<listType>['list']>(
  generateFakeItems(5)
);
const avatar = ref('https://avatars.githubusercontent.com/u/76239030?v=4');
const avartAi = ref(
  'https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png'
);
const switchValue = ref(false);
const loading = ref(false);

function generateFakeItems(count: number): listType[] {
  const messages: listType[] = [];
  for (let i = 0; i < count; i++) {
    const role = i % 2 === 0 ? 'ai' : 'user';
    const placement = role === 'ai' ? 'start' : 'end';
    const key = i + 1;
    messages.push({
      key,
      role,
      placement,
      noStyle: true // If you don't want to use default bubble styles
    });
  }
  return messages;
}

// Set loading for a specific item
function setLoading(loading: boolean) {
  bubbleItems.value[bubbleItems.value.length - 1].loading = loading;
  bubbleItems.value[bubbleItems.value.length - 2].loading = loading;
}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <div style="display: flex; gap: 12px">
      <span>Dynamic content setting <el-switch v-model="switchValue" /></span>
      <span>Custom loading
        <el-switch
          v-model="loading"
          @change="(value: any) => setLoading(value as boolean)"
        /></span>
    </div>
    <BubbleList :list="bubbleItems" max-height="350px">
      <!-- Custom avatar -->
      <template #avatar="{ item }">
        <div class="avatar-wrapper">
          <img :src="item.role === 'ai' ? avartAi : avatar" alt="avatar">
        </div>
      </template>

      <!-- Custom header -->
      <template #header="{ item }">
        <div class="header-wrapper">
          <div class="header-name">
            {{ item.role === 'ai' ? 'Element Plus X 🍧' : '🧁 User' }}
          </div>
        </div>
      </template>

      <!-- Custom bubble content -->
      <template #content="{ item }">
        <div class="content-wrapper">
          <div class="content-text">
            {{
              item.role === 'ai'
                ? `${switchValue ? `#ai-${item.key}：` : ''} 💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~`
                : `${switchValue ? `#user-${item.key}：` : ''}Hahaha, let me try`
            }}
          </div>
        </div>
      </template>

      <!-- Custom footer -->
      <template #footer="{ item }">
        <div class="footer-wrapper">
          <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>
          <div class="footer-time">
            {{ item.role === 'ai' ? '2:32 PM' : '2:33 PM' }}
          </div>
        </div>
      </template>

      <!-- Custom loading -->
      <template #loading="{ item }">
        <div class="loading-container">
          <span>#{{ item.role }}-{{ item.key }}：</span>
          <span>I</span>
          <span>am</span>
          <span>custom</span>
          <span>loading</span>
          <span>content</span>
          <span>oh</span>
          <span>~</span>
        </div>
      </template>
    </BubbleList>
  </div>
</template>

<style scoped lang="less">
.avatar-wrapper {
  width: 40px;
  height: 40px;
  img {
    width: 100%;
    height: 100%;
    border-radius: 50%;
  }
}

.header-wrapper {
  .header-name {
    font-size: 14px;
    color: #979797;
  }
}

.content-wrapper {
  .content-text {
    font-size: 14px;
    color: #333;
    padding: 12px;
    background: linear-gradient(to right, #fdfcfb 0%, #ffd1ab 100%);
    border-radius: 15px;
    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
  }
}

.footer-wrapper {
  display: flex;
  align-items: center;
  gap: 10px;
  .footer-time {
    font-size: 12px;
    margin-top: 3px;
  }
}

.footer-container {
  :deep(.el-button + .el-button) {
    margin-left: 8px;
  }
}

.loading-container {
  font-size: 14px;
  color: #333;
  padding: 12px;
  background: linear-gradient(to right, #fdfcfb 0%, #ffd1ab 100%);
  border-radius: 15px;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}

.loading-container span {
  display: inline-block;
  margin-left: 8px;
}

@keyframes bounce {
  0%,
  100% {
    transform: translateY(5px);
  }
  50% {
    transform: translateY(-5px);
  }
}

.loading-container span:nth-child(4n) {
  animation: bounce 1.2s ease infinite;
}
.loading-container span:nth-child(4n + 1) {
  animation: bounce 1.2s ease infinite;
  animation-delay: 0.3s;
}
.loading-container span:nth-child(4n + 2) {
  animation: bounce 1.2s ease infinite;
  animation-delay: 0.6s;
}
.loading-container span:nth-child(4n + 3) {
  animation: bounce 1.2s ease infinite;
  animation-delay: 0.9s;
}
</style>

Auto Scroll & Scroll to Specific Position

💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~

Hahaha, let me try

Auto Scroll + Scroll to Specified Index

🍑 You can easily use bubbleListRef component instance methods to control scrolling to specified index.

🍒 Component Instance Methods

• scrollToTop()：Scroll to top
• scrollToBottom()：Scroll to bottom
• scrollToBubble(index: number)：Scroll to specified index

<script setup lang="ts">
import type {
  BubbleListItemProps,
  BubbleListProps
} from 'vue-element-plus-x/types/BubbleList';

type listType = BubbleListItemProps & {
  key: number;
  role: 'user' | 'ai';
};

const bubbleItems = ref<BubbleListProps<listType>['list']>(
  generateFakeItems(2)
);

function generateFakeItems(count: number): listType[] {
  const messages: listType[] = [];
  for (let i = 0; i < count; i++) {
    const role = i % 2 === 0 ? 'ai' : 'user';
    const placement = role === 'ai' ? 'start' : 'end';
    const key = i + 1;
    const content =
      role === 'ai'
        ? '💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~'
        : `Hahaha, let me try`;
    const loading = false;
    const shape = 'corner';
    const variant = role === 'ai' ? 'filled' : 'outlined';
    const avatar =
      role === 'ai'
        ? 'https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png'
        : 'https://avatars.githubusercontent.com/u/76239030?v=4';

    messages.push({
      key,
      role,
      placement,
      content,
      loading,
      shape,
      variant,
      avatar,
      avatarSize: '32px'
    });
  }
  return messages;
}

const bubbleListRef = ref();
const num = ref(0);

function addMessage() {
  const i = bubbleItems.value.length;
  const isUser = !!(i % 2);
  const content = isUser
    ? 'Hahaha, let me try'
    : '💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~'.repeat(
        5
      );
  const shape = 'corner';
  const variant = !isUser ? 'filled' : 'outlined';
  const placement = isUser ? 'end' : 'start';
  const avatar = isUser
    ? 'https://avatars.githubusercontent.com/u/76239030?v=4'
    : 'https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png';
  const obj = {
    key: i,
    role: isUser ? 'user' : 'ai',
    content,
    placement,
    avatar,
    shape,
    variant,
    avatarSize: '32px'
  };
  bubbleItems.value.push(obj as listType);
  scrollBottom();
}

function clearMessage() {
  bubbleItems.value = [];
}

function scrollToTop() {
  bubbleListRef.value.scrollToTop();
}

function scrollBottom() {
  bubbleListRef.value.scrollToBottom();
}

function scrollToBubble() {
  bubbleListRef.value.scrollToBubble(num.value);
}

onMounted(() => {
  setTimeout(() => {
    bubbleItems.value.map(item => {
      item.loading = false;
      return item;
    });
  }, 3000);
});
</script>

<template>
  <div class="component-container">
    <div class="top-wrap">
      <div class="btn-list">
        <el-button type="primary" plain @click="addMessage">
          Add Message
        </el-button>
        <el-button type="danger" plain @click="clearMessage">
          Clear Message List
        </el-button>
        <el-button type="primary" plain @click="scrollToTop">
          Scroll to Top
        </el-button>
        <el-button type="primary" plain @click="scrollBottom">
          Scroll to Bottom
        </el-button>
      </div>

      <div class="btn-list">
        <el-input-number
          v-model="num"
          :min="0"
          :max="10"
          controls-position="right"
        />
        <el-button type="primary" plain @click="scrollToBubble">
          Scroll to Bubble {{ num }}
        </el-button>
      </div>
    </div>

    <div class="component-1">
      <BubbleList ref="bubbleListRef" :list="bubbleItems" max-height="350px" />
    </div>
  </div>
</template>

<style scoped lang="less">
.component-container {
  padding: 12px;

  .btn-list {
    display: flex;
    flex-wrap: wrap;
    gap: 12px;
  }

  .top-wrap {
    display: flex;
    flex-direction: column;
    gap: 12px;
    margin-bottom: 24px;
  }
}
</style>

Back to Top Button

Scrollbar display:

Show on hover

Always show

Bottom button loading state:

false

true

Bottom button color:

Bottom button positionDistance from bottom:

Distance from left:

Bottom button size:

💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~

Hahaha, let me try

💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~

Hahaha, let me try

💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~

Hahaha, let me try

💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~

Hahaha, let me try

💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~

Hahaha, let me try

💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~

Hahaha, let me try

Back to Bottom Button + Scrollbar Experience

• Built-in back to bottom button, similar to Douyin.
• Scrollbar appears on mouse hover
• No conflict with built-in auto-scroll, feel free to use

💌 Info

Scrollbar Control Properties

• alwaysShowScrollbar property controls whether to always show scrollbar, default is false.

Bottom Button Customization Properties

• You can set the threshold for the back to bottom button through the backButtonThreshold property, default is 80, meaning the back to bottom button will appear when the scrollbar is 80px away from the bottom.
• showBackButton property controls whether to show the back to bottom button, default is true.
• btnLoading property controls whether to show loading state, default is true.
• btnColor property controls the color of the back to bottom button, default is #409EFF.
• backButtonPosition property controls the position of the back to bottom button, default is { bottom: '20px', left: 'calc(50% - 19px)' } can use % to control, like { bottom: '10%', left: 'calc(50% - 19px)' }.
• btnIconSize property controls the icon size of the back to bottom button, default is 24.

<script setup lang="ts">
import type {
  BubbleListItemProps,
  BubbleListProps
} from 'vue-element-plus-x/types/BubbleList';

type listType = BubbleListItemProps & {
  key: number;
  role: 'user' | 'ai';
};

const list: BubbleListProps<listType>['list'] = generateFakeItems(12);
const alwaysShowScrollbar = ref(false);
const btnLoading = ref(true);
const bottomValue = ref(10);
const leftValue = ref(85);
const backButtonPosition = computed(() => {
  return {
    bottom: `${bottomValue.value}%`,
    left: `${leftValue.value}%`
  };
});
const btnColor = ref('#2D38FF');
const btnSize = ref(40);

function generateFakeItems(count: number): listType[] {
  const messages: listType[] = [];
  for (let i = 0; i < count; i++) {
    const role = i % 2 === 0 ? 'ai' : 'user';
    const placement = role === 'ai' ? 'start' : 'end';
    const key = i + 1;
    const content =
      role === 'ai'
        ? '💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~'.repeat(
            8
          )
        : `Hahaha, let me try`;
    const loading = false;
    const shape = 'corner';
    const variant = role === 'ai' ? 'filled' : 'outlined';
    const avatar =
      role === 'ai'
        ? 'https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png'
        : 'https://avatars.githubusercontent.com/u/76239030?v=4';

    messages.push({
      key,
      role,
      placement,
      content,
      loading,
      shape,
      variant,
      avatar,
      avatarSize: '24px',
      avatarGap: '12px'
    });
  }
  return messages;
}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 24px">
    <div
      style="
        display: flex;
        gap: 5px;
        border: 1px solid gray;
        border-radius: 12px;
        padding: 8px;
        flex-direction: column;
      "
    >
      <span
        >Scrollbar display:
        <el-switch
          v-model="alwaysShowScrollbar"
          inactive-text="Show on hover"
          active-text="Always show"
      /></span>
      <span
        >Bottom button loading state:
        <el-switch
          v-model="btnLoading"
          inactive-text="false"
          active-text="true"
      /></span>
      <span>Bottom button color: <el-color-picker v-model="btnColor" /></span>

      <span>Bottom button position</span>
      <span>Distance from bottom: <el-slider v-model="bottomValue" /></span>
      <span>Distance from left: <el-slider v-model="leftValue" /></span>

      <span>Bottom button size: <el-slider v-model="btnSize" /></span>
    </div>

    <BubbleList
      :list="list"
      max-height="350px"
      :always-show-scrollbar="alwaysShowScrollbar"
      :btn-color="btnColor"
      :btn-loading="btnLoading"
      :back-button-position="backButtonPosition"
      :btn-icon-size="btnSize"
    />
  </div>
</template>

Scroll Complete Event

📌 Warning

This is only needed in very special cases. It is not suitable for streaming output, as it will quickly trigger the typing end event.

💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~

Hahaha, let me try

💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~

Hahaha, let me try

💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~

Hahaha, let me try

💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~

complete Event

This event is triggered when the BubbleList list rendering is complete.

💌 Info

• The @complete event returns an index parameter, indicating the index of the completed BubbleListItem.
• Starting from v2.0.0, the triggerIndices property and TypewriterInstance parameter have been removed.

<script setup lang="ts">
import type {
  BubbleListItemProps,
  BubbleListProps
} from 'vue-element-plus-x/types/BubbleList';

type listType = BubbleListItemProps & {
  key: number;
  role: 'user' | 'ai';
};

function generateFakeItems(count: number): listType[] {
  const messages: listType[] = [];
  for (let i = 0; i < count; i++) {
    const role = i % 2 === 0 ? 'ai' : 'user';
    const placement = role === 'ai' ? 'start' : 'end';
    const key = i + 1;
    const content =
      role === 'ai'
        ? '💖 Thank you for using Element Plus X ! Your support is our strongest motivation for open source ~'
        : `Hahaha, let me try`;
    const loading = false;
    const shape = 'corner';
    const variant = role === 'ai' ? 'filled' : 'outlined';
    const avatar =
      role === 'ai'
        ? 'https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png'
        : 'https://avatars.githubusercontent.com/u/76239030?v=4';

    messages.push({
      key,
      role,
      placement,
      content,
      loading,
      shape,
      variant,
      avatar,
      avatarSize: '24px'
    });
  }
  return messages;
}

const list = ref<BubbleListProps<listType>['list']>(generateFakeItems(7));

function onComplete(index: number) {
  console.log('@complete', index);
}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <BubbleList :list="list" max-height="350px" @complete="onComplete" />
  </div>
</template>

Theme Overrides (themeOverrides)

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

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

Scroll the list to see size changes.

Message 1: used to demonstrate scrolling and the back button.

Message 2: used to demonstrate scrolling and the back button.

Message 3: used to demonstrate scrolling and the back button.

Message 4: used to demonstrate scrolling and the back button.

Message 5: used to demonstrate scrolling and the back button.

Message 6: used to demonstrate scrolling and the back button.

Message 7: used to demonstrate scrolling and the back button.

Message 8: used to demonstrate scrolling and the back button.

Message 9: used to demonstrate scrolling and the back button.

Message 10: used to demonstrate scrolling and the back button.

Message 11: used to demonstrate scrolling and the back button.

Message 12: used to demonstrate scrolling and the back button.

Message 13: used to demonstrate scrolling and the back button.

Message 14: used to demonstrate scrolling and the back button.

Message 15: used to demonstrate scrolling and the back button.

Message 16: used to demonstrate scrolling and the back button.

Message 17: used to demonstrate scrolling and the back button.

Message 18: used to demonstrate scrolling and the back button.

Theme Overrides (themeOverrides)

Override BubbleList --elx-* variables via ConfigProvider.themeOverrides and also style Bubble for a stronger contrast.

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

const enabled = ref(true);

const list = ref(
  Array.from({ length: 18 }).map((_, i) => ({
    content: `Message ${i + 1}: used to demonstrate scrolling and the back button.`,
    placement: i % 2 === 0 ? 'start' : 'end'
  }))
);

const themeOverrides = computed(() => {
  if (!enabled.value) return {};
  return {
    common: {
      'color-primary': '#f97316',
      'border-color': 'rgba(249, 115, 22, 0.38)',
      'fill-color': 'rgba(249, 115, 22, 0.10)',
      'box-shadow': '0 18px 54px rgba(249, 115, 22, 0.22)'
    },
    components: {
      BubbleList: {
        'bubble-list-max-height': '260px',
        'bubble-list-btn-size': '38px'
      },
      Bubble: {
        'bubble-content-max-width': '420px',
        'bubble-bg':
          'linear-gradient(135deg, rgba(249, 115, 22, 0.16), rgba(245, 158, 11, 0.10))',
        'bubble-border-color': 'rgba(249, 115, 22, 0.30)',
        '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(249, 115, 22, 0.18)',
        'bubble-dot-color': '#f97316'
      }
    }
  };
});
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <div
      style="display: flex; align-items: center; justify-content: space-between"
    >
      <div>Scroll the list to see size changes.</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(249, 115, 22, 0.22),
              transparent 60%
            ),
            radial-gradient(
              900px 240px at 100% 20%,
              rgba(245, 158, 11, 0.14),
              transparent 55%
            ),
            rgba(0, 0, 0, 0.02);
          box-shadow: var(--elx-box-shadow);
        "
      >
        <BubbleList :list="list" />
      </div>
    </ConfigProvider>
  </div>
</template>

Using with x-markdown-vue

Starting from v2.0.0, the component library no longer bundles XMarkdown / XMarkdownAsync. For Markdown rendering, 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

Basic Usage

Using with x-markdown-vue

Supports formulas, code blocks, and task lists in list 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 list = ref([
  {
    key: '1',
    content: `### 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}\\]`,
    placement: 'start' as const,
    avatar: 'https://avatars.githubusercontent.com/u/76239030?s=40&v=4',
    role: 'ai'
  },
  {
    key: '2',
    content: 'How can I help you?',
    placement: 'end' as const,
    avatar: 'https://avatars.githubusercontent.com/u/1?s=40&v=4',
    role: 'user'
  },
  {
    key: '3',
    content: `### Block Formulas & Code Block

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

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

Task List:
- [x] Add some task
- [ ] Do some task

\`\`\`typescript
const greeting: string = "Hello World";
console.log(greeting);
\`\`\``,
    placement: 'start' as const,
    avatar: 'https://avatars.githubusercontent.com/u/76239030?s=40&v=4',
    role: 'ai'
  }
]);
</script>

<template>
  <BubbleList :list="list" max-height="500px">
    <template #content="{ item }">
      <div class="markdown-content-wrapper">
        <component
          :is="MarkdownRenderer"
          v-if="MarkdownRenderer"
          :markdown="item.content"
        />
      </div>
    </template>
  </BubbleList>
</template>

<style scoped lang="scss">
.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;
      }
    }
  }
}
</style>

Streaming Rendering

By setting the enable-animate property, you can achieve a typewriter effect:

<template>
  <BubbleList :list="list">
    <template #content="{ item }">
      <MarkdownRenderer :markdown="item.content" :enable-animate="true" />
    </template>
  </BubbleList>
</template>

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

const list = ref([
  { content: '', placement: 'start' } // Streaming content will be updated dynamically
]);
</script>

Props

Name	Type	Required	Default	Description
list	Array	Yes	None	Array containing bubble information. Each element is an object with content, placement, loading, shape, variant, and other Bubble properties to configure the display and style of each bubble. For Markdown, render via the #content slot.
autoScroll	Boolean	No	true	Whether to enable automatic scrolling.
maxHeight	String	No	'-'	Maximum height of the bubble list container.(By default, the height of the wrapper container is inherited)
alwaysShowScrollbar	Boolean	No	false	Whether to always show the scrollbar. Default is false.
backButtonThreshold	Number	No	80	Back to bottom button display threshold. When the scrollbar is more than this distance from the bottom, the button will be shown.
showBackButton	Boolean	No	true	Whether to show the back to bottom button. Default is true.
backButtonPosition	{ bottom: '20px', left: 'calc(50% - 19px)' }	No	{ bottom: '20px', left: 'calc(50% - 19px)' }	Position of the back to bottom button. Default is centered at the bottom.
btnLoading	Boolean	No	true	Whether to enable loading state for the back to bottom button. Default is true.
btnColor	String	No	'#409EFF'	Color of the back to bottom button. Default is '#409EFF'.
btnIconSize	Number	No	24	Icon size of the back to bottom button. Default is 24px.
triggerIndices	'only-last' | 'all' | number[]	No	'only-last'	Index array of bubbles that trigger the complete event. Default is 'only-last'.

Events

Event Name	Parameter	Type	Description
@complete	(instance, index)	Function	Triggered when the typing effect of a bubble is completed.

Ref Instance Methods

Name	Type	Description
scrollToTop	Function	Scroll to the top.
scrollToBottom	Function	Scroll to the bottom.
scrollToBubble	Function	Scroll to the specified bubble index.

Slots

Slot Name	Parameter	Type	Description
#avatar	-	Slot	Custom avatar display content
#header	-	Slot	Custom bubble header content
#content	-	Slot	Custom bubble content
#loading	-	Slot	Custom bubble loading state content
#footer	-	Slot	Custom bubble footer content

Features

1. Smart Scrolling - Automatically tracks the latest message position
2. Deep Customization - Full slot passthrough for bubble components
3. Multiple Scrolling Methods - Scroll to top, bottom, or specific position
4. Multiple Styles - Supports various styles such as round, square, etc.