XDS — Design System

XDSMarkdown@xds/core · Markdown

Usage

Renders a markdown string as XDS-styled components. Use Markdown for user-generated content, AI responses, and documentation — it handles headings, lists, tables, code blocks, and citations with consistent styling.

Best practices

Guidance	Practices
Do	Set headingLevelStart to match the page hierarchy — e.g. start at 3 if the markdown sits inside an h2 section.
Do	Use contentWidth to keep prose at a readable line length in wide layouts.
Don't	Use Markdown for hand-authored layouts — use XDSText and XDSHeading directly when you control the content.

Import

ts
import {XDSMarkdown} from '@xds/core/Markdown'

Props

Prop	Type	Description
childrenrequired	string	The markdown string to render.
density	'default' \| 'compact' (default: 'default')	Controls spacing between block-level elements.
headingLevelStart	1 \| 2 \| 3 \| 4 \| 5 \| 6 (default: 1)	The HTML heading level that markdown # maps to. Shifts all heading levels down to fit the surrounding page hierarchy. Levels exceeding h6 are clamped to h6.
isStreaming	boolean (default: false)	Enables streaming mode — uses incremental parsing and a smooth fade-in animation for chunk-by-chunk text delivery.
onLinkClick	(href: string, event: MouseEvent) => void \| false	Handler for link clicks. Return false to prevent the default navigation behavior.
sources	Record<string, XDSMarkdownSource>	Citation sources keyed by ID. When provided, [id] and 【id】 markers in the markdown that match a key are rendered as citation chips.
citationStyle	'label' \| 'number' (default: 'label')	How citations are displayed inline. 'label' shows a chip with source title, icon, and border. 'number' shows a compact numbered badge.
contentWidth	number \| string	Max width for prose content (paragraphs, headings, lists, blockquotes). Tables and code blocks are unconstrained and can expand to the full container width. Use for readable line lengths in wide layouts.
contentAlign	'start' \| 'center' (default: 'start')	Alignment of prose content within the container when contentWidth is narrower than the available space.
xstyle	StyleXStyles	StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.
className	string	CSS class name for the root element. Prefer xstyle for styling — className is provided for integration with non-StyleX systems.
style	CSSProperties	Inline styles for the root element. Prefer xstyle for styling — inline styles bypass StyleX optimization.
data-testid	string	Test selector for automated testing frameworks.

Examples

Common configurations, variations, and states.

Markdown — Cited ContentMarkdown with citation chips linked to external sources

tsx
'use client';
import {XDSMarkdown} from '@xds/core/Markdown';
const sources = {
  abc1: {
    title: 'Tokyo - Wikipedia',
    url: 'https://en.wikipedia.org/wiki/Tokyo',
    icon: 'https://en.wikipedia.org/favicon.ico',
  },
  def2: {
    title: 'Japan Statistics Bureau - Population',
    url: 'https://www.stat.go.jp/english/',
  },
  ghi3: {
    title: 'World Population Review',
    url: 'https://worldpopulationreview.com/world-cities/tokyo-population',
  },
  jkl4: {
    title: 'Reuters — Tokyo GDP',
    url: 'https://www.reuters.com/markets/',
    icon: 'https://www.reuters.com/favicon.ico',
  },
  mno5: {
    title: 'UN Urbanization Prospects',
    url: 'https://population.un.org/wup/',
  },
};
const content = [
  '## Tokyo Overview',
  '',
  'Tokyo is the capital of Japan with a population of over 14 million[abc1].',
  "It's the most populous metropolitan area in the world[def2][ghi3].",
  '',
  '### Economy',
  '',
  "Tokyo's GDP exceeds $1.9 trillion, making it the largest city economy globally[jkl4].",
  'The metropolitan area is expected to remain the most populous urban agglomeration through 2035[mno5].',
  '',
  '### Key Facts',
  '',
  '- Population: 13.96 million (city proper)[abc1]',
  '- Metro area: 37.4 million[def2]',
  '- GDP: $1.93 trillion[jkl4]',
].join('\n');
export default function MarkdownCitedContent() {
  return (
    <XDSMarkdown sources={sources} density="compact" headingLevelStart={3}>
      {content}
    </XDSMarkdown>
  );
}

Markdown — Compact AI ResponseCompact markdown styled for AI responses with shifted heading levels

tsx
'use client';
import {XDSMarkdown} from '@xds/core/Markdown';
const content = [
  '## Setting Up a Design System',
  '',
  "A design system is more than a component library — it's a **shared language** between design and engineering.",
  '',
  '### 1. Start with Tokens',
  '',
  'Design tokens are the atomic values that define your visual language:',
  '',
  '```typescript',
  'const tokens = {',
  '  color: {',
  "    primary: '#0066FF',",
  "    secondary: '#6B7280',",
  '  },',
  '  spacing: {',
  "    sm: '8px',",
  "    md: '16px',",
  "    lg: '24px',",
  '  },',
  '};',
  '```',
  '',
  '### 2. Component Architecture',
  '',
  'Good components follow these principles:',
  '',
  '- **Composable** — small pieces that combine into complex UIs',
  '- **Accessible** — keyboard navigation and screen reader support built-in',
  '- **Themeable** — visual customization without forking',
  '',
  '> The best design systems are *opinionated enough* to ensure consistency, but *flexible enough* to handle edge cases gracefully.',
].join('\n');
export default function MarkdownCompactAIResponse() {
  return (
    <XDSMarkdown density="compact" headingLevelStart={3}>
      {content}
    </XDSMarkdown>
  );
}

Markdown — Data TableComparison table rendered from a markdown string

tsx
'use client';
import {XDSMarkdown} from '@xds/core/Markdown';
const content = [
  '## Comparison Table',
  '',
  '| Feature | React | Vue | Svelte |',
  '|:--------|:-----:|:---:|-------:|',
  '| Virtual DOM | Yes | Yes | No |',
  '| Bundle Size | ~40KB | ~30KB | ~2KB |',
  '| TypeScript | Native | Plugin | Native |',
  '| Learning Curve | Medium | Easy | Easy |',
].join('\n');
export default function MarkdownDataTable() {
  return <XDSMarkdown>{content}</XDSMarkdown>;
}

Markdown — Rich ContentMarkdown with headings, lists, code blocks, tables, blockquotes, and task lists

tsx
'use client';
import {XDSMarkdown} from '@xds/core/Markdown';
const content = [
  '# XDSMarkdown Demo',
  '',
  'Renders **markdown** with *design-system-consistent* styling.',
  '',
  '## Features',
  '',
  '- Headings mapped to XDS type scale',
  '- **Bold**, *italic*, and ~~strikethrough~~ text',
  '- [Links](https://example.com) with external detection',
  '- Inline `code` and fenced code blocks',
  '',
  '### Code Block',
  '',
  '```typescript',
  'interface User {',
  '  id: string;',
  '  name: string;',
  '}',
  '',
  'function greet(user: User) {',
  '  return `Hello, ${user.name}!`;',
  '}',
  '```',
  '',
  '### Blockquote',
  '',
  '> Design systems free teams to focus on problems that matter.',
  '',
  '### Table',
  '',
  '| Component | Status | Tests |',
  '|:----------|:------:|------:|',
  '| XDSMarkdown | Active | 73 |',
  '| XDSCodeBlock | Active | 44 |',
  '',
  '### Task List',
  '',
  '- [x] Parser',
  '- [x] Renderer',
  '- [ ] Storybook stories',
  '',
  '---',
  '',
  '1. First ordered item',
  '2. Second ordered item',
].join('\n');
export default function MarkdownRichContent() {
  return <XDSMarkdown>{content}</XDSMarkdown>;
}

Showcase source

tsx
'use client';
import {XDSMarkdown} from '@xds/core/Markdown';
const content = [
  '# Markdown Demo',
  '',
  'Renders **markdown** with *design-system-consistent* styling.',
  '',
  '## Features',
  '',
  '- Headings mapped to the XDS type scale',
  '- **Bold**, *italic*, and ~~strikethrough~~ text',
  '- [Links](https://example.com) with external detection',
  '- Inline `code` and fenced code blocks',
  '',
  '> Design systems free teams to focus on problems that matter.',
].join('\n');
export default function MarkdownShowcase() {
  return <XDSMarkdown>{content}</XDSMarkdown>;
}