Skip to content
Latestv1.0.63

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

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 ​

PropertyDescriptionTypeDefault
contentMessage content, supports Markdownstring''
markdownEnable Markdown and syntax highlightingbooleantrue
roleSender role'user' | 'assistant' | 'system''assistant'
placementBubble placement side'start' | 'end'Inferred from role
shapeBubble corner shape'corner' | 'round''round'
variantVisual variant style'filled' | 'outlined' | 'shadow' | 'borderless''filled'
timeTimestamp label at the topstring—
avatarCustom avatar URLstring—
loadingWhether message is being generatedbooleanfalse
typingShow typewriter indicator animationbooleanfalse
streamingEnable incremental streaming renderbooleanfalse
stream-modeStreaming granularity'word' | 'sentence' | 'paragraph''word'
stream-speedStreaming speed (chars per render)number1
stream-intervalStreaming interval (ms)number20
citationsReference citation data listAiCitation[][]
multimodalMultimodal content (images, audio, etc.)AiMultimodal[][]
markdown-optionsMarkdown behavior configurationAiMarkdownOptions{}
structured-dataStructured data (JSON/Table/Mindmap)AiStructuredData—
enable-python-runtimeWhether to enable Python runtimebooleanfalse
python-runtimePython runtime type'browser' | 'remote''browser'
python-api-urlRemote Python API URLstring—
pyodide-urlPyodide CDN URLstring—
enable-sanitizerWhether to enable XSS protectionbooleantrue
sanitizerCustom HTML sanitizer function(html: string) => string—
allowed-tagsWhitelisted HTML tagsstring[]Default safe tags
allowed-attributesWhitelisted HTML attributesstring[]Default safe attributes
allowed-schemesWhitelisted URL protocolsstring[]['http', 'https', 'mailto', 'tel']
theme-overridesTheme variable overridesAiBubbleThemeVars—

Events / Callbacks ​

NameDescriptionType
on-explain-codeCode explanation callback(code: string, language: string) => Promise<string>
on-run-codeCode execution callback(code: string, language: string) => Promise<{ output: string; error?: string }>
on-citation-clickCitation item click callback(citation: AiCitation) => void
on-stream-completeStreaming render complete callback() => void

AiCitation ​

PropertyDescriptionType
idIndex identifierstring | number
titleTitle of sourcestring
urlWeb linkstring
sourceSource site namestring
iconSource iconstring

AiMultimodal ​

PropertyDescriptionType
typeMedia type'image' | 'audio' | 'file' | 'video'
titleTitle/Filenamestring
urlResource URLstring
sizeResource sizestring
extraExtra args (e.g. duration)Record<string, unknown>

AiMarkdownOptions ​

PropertyDescriptionTypeDefault
codeBlockCode block interaction optionsAiCodeBlockOptions{}
mermaidEnable Mermaid diagramsAiMermaidConfig | booleantrue
latexEnable LaTeX math renderingAiLatexOptions | booleantrue
filePreviewEnable built-in file previewAiFilePreviewOptions | booleantrue
linkifyAuto-detect and linkify URLsbooleantrue
htmlAllow raw HTML tagsbooleanfalse
typographerSmart typography enhancementsbooleantrue
allowedProtocolsWhitelisted URL protocolsstring[][]

AiStructuredData ​

PropertyDescriptionType
typeData type'json' | 'table' | 'chart' | 'mindmap' | 'thought-chain'
dataRaw structured payloadunknown
optionsOptional rendering optionsRecord<string, unknown>

Slots ​

NameDescriptionProps
defaultCustom content—
avatarCustom avatar—
headerCustom header—
footerCustom footer—

Python Sandbox Props ​

Property NameDescriptionTypeDefault
enablePythonRuntimeEnable Python code executionbooleanfalse
pythonRuntimePython runtime type'browser' | 'remote''browser'
pythonApiUrlRemote Python API URLstring—
pyodideUrlPyodide CDN URLstringSee note below

XSS Protection Props ​

Property NameDescriptionTypeDefault
enableSanitizerEnable built-in XSS protectionbooleantrue
sanitizerCustom HTML sanitization fn(html: string) => string—
allowedTagsAllowed HTML tags whiteliststring[]See note below
allowedAttributesAllowed attributes whiteliststring[]See note below
allowedSchemesAllowed URL schemes whiteliststring[]['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 ​

NameDescriptionTypeDefault
itemsConversation message data listAiBubbleListItem[][]
virtual-scrollEnable virtual scrolling for large databooleanfalse
heightScroll area container heightnumber | string400
item-heightEstimated height of an itemnumber80
auto-scrollAuto scroll to bottom upon new messagesbooleantrue
loadingWhether in generating or loading statebooleanfalse

AiBubbleList Slots ​

NameDescriptionParameters
bubbleCustom rendering of each dialogue bubble{ item: AiBubbleListItem, index: number }
loadingCustom loading render at list bottom—

AiBubbleList Methods ​

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

MethodDescriptionParameters
scrollToBottomScroll to the very bottom of the list—
scrollToIndexScroll 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 NameDescriptionDefault Value
--yh-ai-bubble-user-bgUser bubble backgroundvar(--yh-color-primary)
--yh-ai-bubble-user-colorUser bubble text colorvar(--yh-color-white)
--yh-ai-bubble-assistant-bgAI bubble backgroundvar(--yh-fill-color-light)
--yh-ai-bubble-assistant-colorAI bubble text colorvar(--yh-text-color-primary)
--yh-ai-bubble-border-radiusBubble border radius12px

Released under the MIT License.