Streamdown

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 [blocked].

Plugin Quick Reference

Math requires CSS:

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

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

References

Use these for deeper implementation details:

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

Example Configurations

Copy and adapt from assets/examples/:

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