Streamdown

1---2name: streamdown3description: >-4  Implement, configure, and customize Streamdown — a streaming-optimized React Markdown renderer5  with syntax highlighting, Mermaid diagrams, math rendering, and CJK support. Use when working6  with Streamdown setup, configuration, plugins, styling, security, or integration with AI7  streaming (e.g., Vercel AI SDK). Triggers on: (1) Installing or setting up Streamdown,8  (2) Configuring plugins (code, mermaid, math, cjk), (3) Styling or theming Streamdown output,9  (4) Integrating with AI chat/streaming, (5) Configuring security, link safety, or custom HTML tags,10  (6) Using carets, static mode, or custom components, (7) Troubleshooting Tailwind, Shiki, or Vite issues.11---12 13# Streamdown14 15Streaming-optimized React Markdown renderer. Drop-in replacement for `react-markdown` with built-in streaming support, security, and interactive controls.16 17## Quick Setup18 19### 1. Install20 21```bash22npm install streamdown23```24 25Optional plugins (install only what's needed):26```bash27npm install @streamdown/code @streamdown/mermaid @streamdown/math @streamdown/cjk28```29 30### 2. Configure Tailwind CSS (Required)31 32**This is the most commonly missed step.** Streamdown uses Tailwind for styling and the dist files must be scanned.33 34**Tailwind v4** — add to `globals.css`:35```css36@source "../node_modules/streamdown/dist/*.js";37```38 39Add plugin `@source` lines **only for packages you have installed** (omitting uninstalled plugins avoids Tailwind errors). See plugin pages for exact paths:40- Code: `@source "../node_modules/@streamdown/code/dist/*.js";`41- CJK: `@source "../node_modules/@streamdown/cjk/dist/*.js";`42- Math: `@source "../node_modules/@streamdown/math/dist/*.js";`43- Mermaid: `@source "../node_modules/@streamdown/mermaid/dist/*.js";`44 45 46**Tailwind v3** — add to `tailwind.config.js`:47```js48module.exports = {49  content: [50    "./app/**/*.{js,ts,jsx,tsx,mdx}",51    "./node_modules/streamdown/dist/*.js",52  ],53};54```55 56### 3. Basic Usage57 58```tsx59import { Streamdown } from 'streamdown';60 61<Streamdown>{markdown}</Streamdown>62```63 64### 4. With AI Streaming (Vercel AI SDK)65 66```tsx67'use client';68import { useChat } from '@ai-sdk/react';69import { Streamdown } from 'streamdown';70import { code } from '@streamdown/code';71 72export default function Chat() {73  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat();74 75  return (76    <>77      {messages.map((msg, i) => (78        <Streamdown79          key={msg.id}80          plugins={{ code }}81          caret="block"82          isAnimating={isLoading && i === messages.length - 1 && msg.role === 'assistant'}83        >84          {msg.content}85        </Streamdown>86      ))}87      <form onSubmit={handleSubmit}>88        <input value={input} onChange={handleInputChange} disabled={isLoading} />89      </form>90    </>91  );92}93```94 95### 5. Static Mode (Blogs, Docs)96 97```tsx98<Streamdown mode="static" plugins={{ code }}>99  {content}100</Streamdown>101```102 103## Key Props104 105| Prop | Type | Default | Purpose |106|------|------|---------|---------|107| `children` | `string` | — | Markdown content |108| `mode` | `"streaming" \| "static"` | `"streaming"` | Rendering mode |109| `plugins` | `{ code?, mermaid?, math?, cjk? }` | — | Feature plugins |110| `isAnimating` | `boolean` | `false` | Streaming indicator |111| `caret` | `"block" \| "circle"` | — | Cursor style |112| `components` | `Components` | — | Custom element overrides |113| `controls` | `boolean \| object` | `true` | Interactive buttons |114| `linkSafety` | `LinkSafetyConfig` | `{ enabled: true }` | Link confirmation modal |115| `shikiTheme` | `[light, dark]` | `['github-light', 'github-dark']` | Code themes |116| `className` | `string` | — | Container class |117| `allowedElements` | `string[]` | all | Tag names to allow |118| `disallowedElements` | `string[]` | `[]` | Tag names to disallow |119| `allowElement` | `AllowElement` | — | Custom element filter |120| `unwrapDisallowed` | `boolean` | `false` | Keep children of disallowed elements |121| `skipHtml` | `boolean` | `false` | Ignore raw HTML |122| `urlTransform` | `UrlTransform` | `defaultUrlTransform` | Transform/sanitize URLs |123 124For full API reference, see [references/api.md](references/api.md).125 126## Plugin Quick Reference127 128| Plugin | Package | Purpose |129|--------|---------|---------|130| Code | `@streamdown/code` | Syntax highlighting (Shiki, 200+ languages) |131| Mermaid | `@streamdown/mermaid` | Diagrams (flowcharts, sequence, etc.) |132| Math | `@streamdown/math` | LaTeX via KaTeX (requires CSS import) |133| CJK | `@streamdown/cjk` | Chinese/Japanese/Korean text support |134 135**Math requires CSS:**136```tsx137import 'katex/dist/katex.min.css';138```139 140For plugin configuration details, see [references/plugins.md](references/plugins.md).141 142## References143 144Use these for deeper implementation details:145 146- **[references/api.md](references/api.md)** — Complete props, types, and interfaces147- **[references/plugins.md](references/plugins.md)** — Plugin setup, configuration, and customization148- **[references/styling.md](references/styling.md)** — CSS variables, data attributes, custom components, theme examples149- **[references/security.md](references/security.md)** — Hardening, link safety, custom HTML tags, production config150- **[references/features.md](references/features.md)** — Carets, remend, static mode, controls, GFM, memoization, troubleshooting151 152## Example Configurations153 154Copy and adapt from `assets/examples/`:155 156- **[basic-streaming.tsx](assets/examples/basic-streaming.tsx)** — Minimal AI chat with Vercel AI SDK157- **[with-caret.tsx](assets/examples/with-caret.tsx)** — Streaming with block caret cursor158- **[full-featured.tsx](assets/examples/full-featured.tsx)** — All plugins, carets, link safety, controls159- **[static-mode.tsx](assets/examples/static-mode.tsx)** — Blog/docs rendering160- **[custom-security.tsx](assets/examples/custom-security.tsx)** — Strict security for AI content161 162## Common Gotchas163 1641. **Tailwind styles missing** — Add `@source` directive or `content` entry for `node_modules/streamdown/dist/*.js`1652. **Math not rendering** — Import `katex/dist/katex.min.css`1663. **Caret not showing** — Both `caret` prop AND `isAnimating={true}` are required1674. **Copy buttons during streaming** — Disabled automatically when `isAnimating={true}`1685. **Link safety modal appearing** — Enabled by default; disable with `linkSafety={{ enabled: false }}`1696. **Shiki warning in Next.js** — Install `shiki` explicitly, add to `transpilePackages`1707. **`allowedTags` not working** — Only works with default rehype plugins1718. **Math uses `$$` not `$`** — Single dollar is disabled by default to avoid currency conflicts