streamdown

name: streamdown description: >- Implement, configure, and customize Streamdown — a streaming-optimized React Markdown renderer with syntax highlighting, Mermaid diagrams, math rendering, and CJK support. Use when working with Streamdown setup, configuration, plugins, styling, security, or integration with AI streaming (e.g., Vercel AI SDK). Triggers on: (1) Installing or setting up Streamdown, (2) Configuring plugins (code, mermaid, math, cjk), (3) Styling or theming Streamdown output, (4) Integrating with AI chat/streaming, (5) Configuring security, link safety, or custom HTML tags, (6) Using carets, static mode, or custom components, (7) Troubleshooting Tailwind, Shiki, or Vite issues.

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

npm install streamdown

Optional plugins (install only what's needed):

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:

@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:

module.exports = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
    "./node_modules/streamdown/dist/*.js",
  ],
};

3. Basic Usage

import { Streamdown } from 'streamdown';

<Streamdown>{markdown}</Streamdown>

4. With AI Streaming (Vercel AI SDK)

'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)

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

Key Props

For full API reference, see references/api.md.

Plugin Quick Reference

Math requires CSS:

import 'katex/dist/katex.min.css';

For plugin configuration details, see references/plugins.md.

References

Use these for deeper implementation details:

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

Example Configurations

Copy and adapt from assets/examples/:

• basic-streaming.tsx — Minimal AI chat with Vercel AI SDK
• with-caret.tsx — Streaming with block caret cursor
• full-featured.tsx — All plugins, carets, link safety, controls
• static-mode.tsx — Blog/docs rendering
• 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