streamdown

---
name: streamdown
description: >-
license: Apache-2.0
---

# Streamdown

Streaming-optimized React Markdown renderer. Drop-in replacement for `react-markdown` with built-in streaming support, security, and interactive controls.

## Quick Setup

### 1. Install

```bash
npm install streamdown
```

Optional plugins (install only what's needed):
```bash
npm install @streamdown/code @streamdown/mermaid @streamdown/math @streamdown/cjk
```

### 2. Configure Tailwind CSS (Required)

**This is the most commonly missed step.** Streamdown uses Tailwind for styling and the dist files must be scanned.

**Tailwind v4** — add to `globals.css`:
```css
@source "../node_modules/streamdown/dist/*.js";
```

Add plugin `@source` lines **only for packages you have installed** (omitting uninstalled plugins avoids Tailwind errors). See plugin pages for exact paths:
- Code: `@source "../node_modules/@streamdown/code/dist/*.js";`
- CJK: `@source "../node_modules/@streamdown/cjk/dist/*.js";`
- Math: `@source "../node_modules/@streamdown/math/dist/*.js";`
- Mermaid: `@source "../node_modules/@streamdown/mermaid/dist/*.js";`


**Tailwind v3** — add to `tailwind.config.js`:
```js
module.exports = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
    "./node_modules/streamdown/dist/*.js",
  ],
};
```

### 3. Basic Usage

```tsx
import { Streamdown } from 'streamdown';

<Streamdown>{markdown}</Streamdown>
```

### 4. With AI Streaming (Vercel AI SDK)

```tsx
'use client';
import { useChat } from '@ai-sdk/react';
import { Streamdown } from 'streamdown';
import { code } from '@streamdown/code';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat();

  return (
    <>
      {messages.map((msg, i) => (
        <Streamdown
          key={msg.id}
          plugins={{ code }}
          caret="block"
          isAnimating={isLoading && i === messages.length - 1 && msg.role === 'assistant'}
        >
          {msg.content}
        </Streamdown>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} disabled={isLoading} />
      </form>
    </>
  );
}
```

### 5. Static Mode (Blogs, Docs)

```tsx
<Streamdown mode="static" plugins={{ code }}>
  {content}
</Streamdown>
```

## Key Props

| Prop | Type | Default | Purpose |
|------|------|---------|---------|
| `children` | `string` | — | Markdown content |
| `mode` | `"streaming" \| "static"` | `"streaming"` | Rendering mode |
| `plugins` | `{ code?, mermaid?, math?, cjk? }` | — | Feature plugins |
| `isAnimating` | `boolean` | `false` | Streaming indicator |
| `caret` | `"block" \| "circle"` | — | Cursor style |
| `components` | `Components` | — | Custom element overrides |
| `controls` | `boolean \| object` | `true` | Interactive buttons |
| `linkSafety` | `LinkSafetyConfig` | `{ enabled: true }` | Link confirmation modal |
| `shikiTheme` | `[light, dark]` | `['github-light', 'github-dark']` | Code themes |
| `className` | `string` | — | Container class |
| `allowedElements` | `string[]` | all | Tag names to allow |
| `disallowedElements` | `string[]` | `[]` | Tag names to disallow |
| `allowElement` | `AllowElement` | — | Custom element filter |
| `unwrapDisallowed` | `boolean` | `false` | Keep children of disallowed elements |
| `skipHtml` | `boolean` | `false` | Ignore raw HTML |
| `urlTransform` | `UrlTransform` | `defaultUrlTransform` | Transform/sanitize URLs |

For full API reference, see [references/api.md](references/api.md).

## Plugin Quick Reference

| Plugin | Package | Purpose |
|--------|---------|---------|
| Code | `@streamdown/code` | Syntax highlighting (Shiki, 200+ languages) |
| Mermaid | `@streamdown/mermaid` | Diagrams (flowcharts, sequence, etc.) |
| Math | `@streamdown/math` | LaTeX via KaTeX (requires CSS import) |
| CJK | `@streamdown/cjk` | Chinese/Japanese/Korean text support |

**Math requires CSS:**
```tsx
import 'katex/dist/katex.min.css';
```

For plugin configuration details, see [references/plugins.md](references/plugins.md).

## References

Use these for deeper implementation details:

- **[references/api.md](references/api.md)** — Complete props, types, and interfaces
- **[references/plugins.md](references/plugins.md)** — Plugin setup, configuration, and customization
- **[references/styling.md](references/styling.md)** — CSS variables, data attributes, custom components, theme examples
- **[references/security.md](references/security.md)** — Hardening, link safety, custom HTML tags, production config
- **[references/features.md](references/features.md)** — Carets, remend, static mode, controls, GFM, memoization, troubleshooting

## Example Configurations

Copy and adapt from `assets/examples/`:

- **[basic-streaming.tsx](assets/examples/basic-streaming.tsx)** — Minimal AI chat with Vercel AI SDK
- **[with-caret.tsx](assets/examples/with-caret.tsx)** — Streaming with block caret cursor
- **[full-featured.tsx](assets/examples/full-featured.tsx)** — All plugins, carets, link safety, controls
- **[static-mode.tsx](assets/examples/static-mode.tsx)** — Blog/docs rendering
- **[custom-security.tsx](assets/examples/custom-security.tsx)** — Strict security for AI content

## Common Gotchas

1. **Tailwind styles missing** — Add `@source` directive or `content` entry for `node_modules/streamdown/dist/*.js`
2. **Math not rendering** — Import `katex/dist/katex.min.css`
3. **Caret not showing** — Both `caret` prop AND `isAnimating={true}` are required
4. **Copy buttons during streaming** — Disabled automatically when `isAnimating={true}`
5. **Link safety modal appearing** — Enabled by default; disable with `linkSafety={{ enabled: false }}`
6. **Shiki warning in Next.js** — Install `shiki` explicitly, add to `transpilePackages`
7. **`allowedTags` not working** — Only works with default rehype plugins
8. **Math uses `$$` not `$`** — Single dollar is disabled by default to avoid currency conflicts