AiBubble

AiBubble is the core component for AI conversation interaction.

Basic Usage

Display visual differences between user and assistant, along with loading animations.

Basic Usage

Advanced Features & Variants

AiBubble features a built-in Markdown engine and highlight.js parsing. It offers various variants (variant), shapes (shape), and specialized metadata support.

Advanced Combo

Typing Effect & Visual Feedback

More than just a loading state, it allows text to flow out with a flickering cursor, mimicking the AI writing experience.

TIP

Enhanced Feedback: When typing mode is enabled, the component automatically appends a "Blinking Cursor" to the last line and adds a "Gentle Ripple" glow to the bubble background, making the generation process feel alive.

• Streaming Performance: Under the hood, we introduced a requestAnimationFrame debouncing queue. When receiving high-frequency text payloads in typing mode, it stabilizes the intense Markdown parsing and keeps your browser refreshing at a seamless 60 frames per second without blocking the main thread!

Typewriter Effect

Citations & Reference Tooltip

AI responses often need verification to avoid hallucinations. Besides appending a raw list at the bottom, we injected a smart Citation syntax interceptor natively. If the citations array is present and the model outputs Markdown tags like [1] or [2]: the bubble automatically transforms them into interactive, softly-glowing citation badges. 💡 Try it: Hover your mouse over [1], [2], or [3] in the text below to trigger the elegant floating citation popover.

Citations

Multimodal Rendering

The component supports direct display of various media formats, including image grids, audio players with waveform animations, and file/download cards.

Multimodal

Advanced Configuration: Markdown & Structured Data

With markdown-options, structured-data, and callbacks on-run-code / on-explain-code, you can turn AiBubble into a richer Markdown and data visualization surface.

Advanced Configuration: Markdown & Structured Data

More Examples

Custom Avatar

Customize the bubble avatar using the avatar prop or #avatar slot.

Custom Avatar

Custom Header/Footer Slots

Use #header and #footer slots to customize the bubble's supplementary information area.

Custom Header/Footer Slots

Bubble Placement

Control the bubble alignment using the placement prop.

Bubble Placement

System Message

Use role="system" to display system notices or announcements.

System Message

Plain Text Mode

Disable Markdown parsing to display plain text content.

Plain Text Mode

Full Conversation Flow

Demonstrate a complete multi-turn conversation.

Full Conversation Flow

JSON Structured Data

Display structured JSON data.

JSON Structured Data

Thought Chain

Use the thought-chain type to display the thinking process.

Thought Chain

Streaming Code Output

Code blocks support true streaming output - execution results are displayed in real-time line by line, mimicking a real terminal experience.

Features:

• Real-time streaming display of execution results
• Color-coded prefixes for different output types (> running, ← return value, ✓ success, ✗ error)
• Supports both WebContainer and browser runtime environments

Streaming Code Output

Online Code Runner: Monaco + WebContainer

By setting runtime: 'webcontainer' inside markdown-options.codeBlock, code blocks will run inside an embedded WebContainer sandbox and use an inline Monaco editor for live editing.

Local Development Note: WebContainer requires the following to run in browser:

• HTTPS or localhost environment
• Server must include these headers:
  • Cross-Origin-Embedder-Policy: require-corp
  • Cross-Origin-Opener-Policy: same-origin
• Browser must support SharedArrayBuffer

If conditions are not met, the component automatically falls back to in-browser execution.

The Playground dev server is pre-configured with these headers, so you can test WebContainer functionality directly.

Monaco + WebContainer Runner

Theme Overrides

Besides global CSS variables, you can use the theme-overrides property for granular instance-level styling.

Instance Level Overrides

API

Props

Property	Description	Type	Default
content	Message content, supports Markdown	string	''
markdown	Enable Markdown and syntax highlighting	boolean	true
role	Sender role	'user' | 'assistant' | 'system'	'assistant'
placement	Bubble placement side	'start' | 'end'	Inferred from role
shape	Bubble corner shape	'corner' | 'round'	'round'
variant	Visual variant style	'filled' | 'outlined' | 'shadow' | 'borderless'	'filled'
time	Timestamp label at the top	string	—
avatar	Custom avatar URL	string	—
loading	Whether message is being generated	boolean	false
typing	Show typewriter indicator animation	boolean	false
streaming	Enable incremental streaming render	boolean	false
stream-mode	Streaming granularity	'word' | 'sentence' | 'paragraph'	'word'
stream-speed	Streaming speed (chars per render)	number	1
stream-interval	Streaming interval (ms)	number	20
citations	Reference citation data list	AiCitation[]	[]
multimodal	Multimodal content (images, audio, etc.)	AiMultimodal[]	[]
markdown-options	Markdown behavior configuration	AiMarkdownOptions	{}
structured-data	Structured data (JSON/Table/Mindmap)	AiStructuredData	—
enable-python-runtime	Whether to enable Python runtime	boolean	false
python-runtime	Python runtime type	'browser' | 'remote'	'browser'
python-api-url	Remote Python API URL	string	—
pyodide-url	Pyodide CDN URL	string	—
enable-sanitizer	Whether to enable XSS protection	boolean	true
sanitizer	Custom HTML sanitizer function	(html: string) => string	—
allowed-tags	Whitelisted HTML tags	string[]	Default safe tags
allowed-attributes	Whitelisted HTML attributes	string[]	Default safe attributes
allowed-schemes	Whitelisted URL protocols	string[]	['http', 'https', 'mailto', 'tel']
theme-overrides	Theme variable overrides	AiBubbleThemeVars	—

Events / Callbacks

Name	Description	Type
on-explain-code	Code explanation callback	(code: string, language: string) => Promise<string>
on-run-code	Code execution callback	(code: string, language: string) => Promise<{ output: string; error?: string }>
on-citation-click	Citation item click callback	(citation: AiCitation) => void
on-stream-complete	Streaming render complete callback	() => void

AiCitation

Property	Description	Type
id	Index identifier	string | number
title	Title of source	string
url	Web link	string
source	Source site name	string
icon	Source icon	string

AiMultimodal

Property	Description	Type
type	Media type	'image' | 'audio' | 'file' | 'video'
title	Title/Filename	string
url	Resource URL	string
size	Resource size	string
extra	Extra args (e.g. duration)	Record<string, unknown>

AiMarkdownOptions

Property	Description	Type	Default
codeBlock	Code block interaction options	AiCodeBlockOptions	{}
mermaid	Enable Mermaid diagrams	AiMermaidConfig | boolean	true
latex	Enable LaTeX math rendering	AiLatexOptions | boolean	true
filePreview	Enable built-in file preview	AiFilePreviewOptions | boolean	true
linkify	Auto-detect and linkify URLs	boolean	true
html	Allow raw HTML tags	boolean	false
typographer	Smart typography enhancements	boolean	true
allowedProtocols	Whitelisted URL protocols	string[]	[]

AiStructuredData

Property	Description	Type
type	Data type	'json' | 'table' | 'chart' | 'mindmap' | 'thought-chain'
data	Raw structured payload	unknown
options	Optional rendering options	Record<string, unknown>

Slots

Name	Description	Props
default	Custom content	—
avatar	Custom avatar	—
header	Custom header	—
footer	Custom footer	—

Python Sandbox Props

Property Name	Description	Type	Default
enablePythonRuntime	Enable Python code execution	boolean	false
pythonRuntime	Python runtime type	'browser' | 'remote'	'browser'
pythonApiUrl	Remote Python API URL	string	—
pyodideUrl	Pyodide CDN URL	string	See note below

XSS Protection Props

Property Name	Description	Type	Default
enableSanitizer	Enable built-in XSS protection	boolean	true
sanitizer	Custom HTML sanitization fn	(html: string) => string	—
allowedTags	Allowed HTML tags whitelist	string[]	See note below
allowedAttributes	Allowed attributes whitelist	string[]	See note below
allowedSchemes	Allowed URL schemes whitelist	string[]	['http', 'https', 'mailto', 'tel']

Python Sandbox & XSS Protection Examples

Browser-side Python Runtime (Pyodide)

Browser-side Python Runtime

Remote Python API

Remote Python API

XSS Protection Example

XSS Protection

Custom Whitelist

Custom Whitelist

AiBubbleList Virtual Scroll (Large List Performance)

When the conversation history is extremely long (e.g., more than 100 items), rendering too many DOM nodes can cause page scrolling lag. AiBubbleList integrates a powerful virtual scroll engine, maintaining a smooth 60fps scrolling experience even with 10,000 messages.

Virtual Scroll - Performance Optimization

AiBubbleList Props

Name	Description	Type	Default
items	Conversation message data list	AiBubbleListItem[]	[]
virtual-scroll	Enable virtual scrolling for large data	boolean	false
height	Scroll area container height	number | string	400
item-height	Estimated height of an item	number	80
auto-scroll	Auto scroll to bottom upon new messages	boolean	true
loading	Whether in generating or loading state	boolean	false

AiBubbleList Slots

Name	Description	Parameters
bubble	Custom rendering of each dialogue bubble	{ item: AiBubbleListItem, index: number }
loading	Custom loading render at list bottom	—

AiBubbleList Methods

You can get the component instance using ref and call the following methods:

Method	Description	Parameters
scrollToBottom	Scroll to the very bottom of the list	—
scrollToIndex	Scroll to a specific index virtually	(index: number)

Use in Nuxt

This component fully supports Nuxt 3/4. In Nuxt projects, the component will be automatically imported.

For detailed configuration, please see Nuxt Integration.

Theme Variables

Variable Name	Description	Default Value
--yh-ai-bubble-user-bg	User bubble background	var(--yh-color-primary)
--yh-ai-bubble-user-color	User bubble text color	var(--yh-color-white)
--yh-ai-bubble-assistant-bg	AI bubble background	var(--yh-fill-color-light)
--yh-ai-bubble-assistant-color	AI bubble text color	var(--yh-text-color-primary)
--yh-ai-bubble-border-radius	Bubble border radius	12px