Introduction

Stream-friendly, extensible Markdown rendering component. Aligns with the core capabilities of @ant-design/x-markdown@2.10.0: formulas, code highlighting, Mermaid, stream syntax, and custom component mapping.

When to use

• Render Markdown content in chat bubbles, messages, and other scenarios
• Use streaming and useStreaming when streaming output is needed
• Use components mapping when custom headers, code blocks, Mermaid, and other nodes are needed

More detailed pages:

• Code examples and full API
• Plugins: Latex, HighlightCode, Mermaid, Custom transform
• Themes light / dark
• Streaming syntax
• Overview of component mappings

Examples

Basic usage

# Hello World ### Welcome to XMarkdown! - Item 1 - Item 2 - Item 3 ```js const a = 1; ```

Hello World

Welcome to XMarkdown!

• Item 1
• Item 2
• Item 3

const a = 1;

Basic usage

You can render by passing a Markdown string through content.

<script setup lang="tsx">
defineOptions({ name: 'AXXMarkdownBasicV2' });

import { computed, ref } from 'vue';
import { Flex, Input, theme } from 'ant-design-vue';
import { XMarkdown } from '@ant-design-x-vue/x-markdown';
import '@ant-design-x-vue/x-markdown/themes/light.css';
import '@ant-design-x-vue/x-markdown/themes/dark.css';
import { isDarkColor } from '../_shared/playground-shell';

const { token } = theme.useToken();
const markdownClass = computed(() => (
  isDarkColor(token.value.colorBgContainer) ? 'x-markdown-dark' : 'x-markdown-light'
));

const content = ref(`# Hello World

### Welcome to XMarkdown!

- Item 1
- Item 2
- Item 3

\`\`\`js
const a = 1;
\`\`\`
`);

defineRender(() => (
  <Flex vertical gap={16}>
    <Input.TextArea v-model:value={content.value} rows={8} />
    <div style={{
      border: `1px solid ${token.value.colorBorderSecondary}`,
      borderRadius: '4px',
      padding: '16px',
      minHeight: '120px',
    }}>
      <XMarkdown className={markdownClass.value} content={content.value} />
    </div>
  </Flex>
));
</script>

Hide source

Custom components mapping

# Custom Blue Title ## Normal H2 Paragraph with **bold** and *italic*.

Custom Blue Title

Normal H2

Paragraph with bold and italic.

Custom components mapping

Map HTML tags to custom Vue components through components, which can receive props like domNode, streamStatus, children, etc.

<script setup lang="tsx">
defineOptions({ name: 'AXXMarkdownComponentsV2' });

import { computed, ref, h } from 'vue';
import { XMarkdown } from '@ant-design-x-vue/x-markdown';
import type { ComponentProps } from '@ant-design-x-vue/x-markdown';
import { Flex, Input, theme } from 'ant-design-vue';

const { token } = theme.useToken();
const wrapStyle = computed(() => ({
  border: `1px solid ${token.value.colorBorderSecondary}`,
  borderRadius: '4px',
  padding: '16px',
  minHeight: '100px',
}));

const CustomH1 = (props: ComponentProps) => {
  return h('h1', { style: { color: '#1890ff' }, ...props }, props.children);
};

const components = {
  h1: CustomH1,
};

const content = ref(`# Custom Blue Title

## Normal H2

Paragraph with **bold** and *italic*.
`);

defineRender(() => (
  <Flex vertical gap={16}>
    <Input.TextArea v-model:value={content.value} rows={6} />
    <div style={wrapStyle.value}>
      <XMarkdown content={content.value} components={components} />
    </div>
  </Flex>
));
</script>

Hide source

Streaming render

Status: idle

Streaming render

Use streaming to indicate streaming state, combined with useStreaming to handle content and state.

<script setup lang="tsx">
defineOptions({ name: 'AXXMarkdownStreamingV2' });

import { computed, ref } from 'vue';
import { XMarkdown, useStreaming } from '@ant-design-x-vue/x-markdown';
import { Button, Flex, Space, theme } from 'ant-design-vue';

const { token } = theme.useToken();
const wrapStyle = computed(() => ({
  border: `1px solid ${token.value.colorBorderSecondary}`,
  borderRadius: '4px',
  padding: '16px',
  minHeight: '120px',
}));

const fullContent = `# Streaming Demo

Content appears **progressively**.

- Step 1
- Step 2
- Step 3
`;

const content = ref('');
const streaming = ref(false);
const { status, displayedContent } = useStreaming({
  content,
  streaming,
  onComplete: () => console.log('stream complete'),
});

const startStream = () => {
  content.value = '';
  streaming.value = true;
  let i = 0;
  const timer = setInterval(() => {
    if (i < fullContent.length) {
      content.value = fullContent.slice(0, i + 3);
      i += 3;
    } else {
      streaming.value = false;
      clearInterval(timer);
    }
  }, 50);
};

defineRender(() => (
  <Flex vertical gap={16}>
    <Space>
      <Button type="primary" onClick={startStream}>
        Start streaming
      </Button>
      <span>Status: {status.value}</span>
    </Space>
    <div style={wrapStyle.value}>
      <XMarkdown content={displayedContent.value} streaming={streaming.value} />
    </div>
  </Flex>
));
</script>

Hide source

API

The full table (including children, paragraphTag, openLinksInNewTab, dompurifyConfig, componentsProps, escapeRawHtml, disableDefaultStyles, protectCustomTagNewlines, disableCustomTagBlockMarkdown, rootClassName, style, etc.) can be found in Code Examples · API. Common fields are listed here:

XMarkdownProps

Prop	Description	Type	Default
content	Markdown content	string	-
children	Alias for content	string	-
streaming	Streaming configuration. Boolean indicates whether it is still outputting; object supports hasNextChunk, enableAnimation, animationConfig, incompleteMarkdownComponentMap	boolean | StreamingOption	-
components	Maps tag names to custom Vue components (e.g., h1, pre, code, mermaid, think)	Record\<string, Component\>	-
paragraphTag	Paragraph HTML tag, avoid illegal nesting of custom block components	string	'p'
plugins	List of plugins, transforms content before parsing	any[]	-
config	Marked parsing configuration	MarkedConfig	-
openLinksInNewTab	Add target="_blank" to all links	boolean	false
dompurifyConfig	DOMPurify sanitization configuration	DOMPurify.Config	-
className	Root class name	string	-
rootClassName	Alias of className	string	-
style	Root inline style	CSSProperties	-

StreamingOption / AnimationConfig

Field	Description	Default
hasNextChunk	There is another chunk following. Unclosed syntax is not fully parsed as Markdown	false
enableAnimation	Text fade-in	false
animationConfig.fadeDuration	Fade-in duration (milliseconds)	200
animationConfig.easing	Easing	'ease-in-out'
incompleteMarkdownComponentMap	Component names for unfinished syntax (token is link / image / html / emphasis / list / table)	{}

ComponentProps (custom component props)

Prop	Description	Type
domNode	Parsed DOM node information (name, attribs, children)	DOMNode
streamStatus	When a custom tag is not closed, it is 'loading'; after closing, it is 'done'. code can read data-state	`'loading'
block	Only for code: when data-block="true", it is block-level code	boolean
children	Child content (VNode or text)	`VNode[]
others	Standard HTML attributes and data-* etc.	Record\<string, any\>

useStreaming

Used as a composable function for streaming content.

Argument	Description	Type
content	Content ref	Ref\<string\>
streaming	Ref indicating whether streaming is in progress (optional)	Ref\<boolean\>
onComplete	Callback when streaming ends	() => void

Return value	Description	Type
displayedContent	Currently displayed content	Ref\<string\>
status	Status: idle	streaming
isStreaming	Whether it is streaming	Ref\<boolean\>

Exports

• XMarkdown - Main component
• AnimationText - Text fade-in component (streaming.enableAnimation)
• useStreaming - Streaming composition function
• parseMarkdown(content, config?) - Parse Markdown into HTML
• htmlToVNode(html, options?) - Convert HTML to VNode (supports components, streamStatus)