streamdown

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Streamdown

Streaming-optimized React Markdown renderer. Drop-in replacement for

react-markdown

with built-in streaming support, security, and interactive controls.

一款针对流式传输优化的React Markdown渲染器，可直接替代

react-markdown

，内置流式传输支持、安全防护和交互控制功能。

Quick Setup

快速开始

1. Install

1. 安装

bash

npm install streamdown

Optional plugins (install only what's needed):

bash

npm install @streamdown/code @streamdown/mermaid @streamdown/math @streamdown/cjk

bash

npm install streamdown

可选插件（仅安装所需插件）：

bash

npm install @streamdown/code @streamdown/mermaid @streamdown/math @streamdown/cjk

2. Configure Tailwind CSS (Required)

2. 配置Tailwind CSS（必填）

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";

Tailwind v3 — add to

tailwind.config.js

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

这是最容易遗漏的步骤。 Streamdown使用Tailwind进行样式渲染，必须扫描其dist文件。

Tailwind v4 —— 在

globals.css

中添加：

css

@source "../node_modules/streamdown/dist/*.js";

Tailwind v3 —— 在

tailwind.config.js

中添加：

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

3. Basic Usage

3. 基础用法

tsx

import { Streamdown } from 'streamdown';

<Streamdown>{markdown}</Streamdown>

tsx

import { Streamdown } from 'streamdown';

<Streamdown>{markdown}</Streamdown>

4. With AI Streaming (Vercel AI SDK)

4. 与AI流式传输集成（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>
    </>
  );
}

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)

5. 静态模式（博客、文档）

tsx

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

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

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

属性	类型	默认值	用途
`children`	`string`	—	Markdown内容
`mode`	`"streaming" \| "static"`	`"streaming"`	渲染模式
`plugins`	`{ code?, mermaid?, math?, cjk? }`	—	功能插件
`isAnimating`	`boolean`	`false`	流式传输状态指示器
`caret`	`"block" \| "circle"`	—	光标样式
`components`	`Components`	—	自定义元素覆盖
`controls`	`boolean \| object`	`true`	交互按钮
`linkSafety`	`LinkSafetyConfig`	`{ enabled: true }`	链接确认弹窗
`shikiTheme`	`[light, dark]`	`['github-light', 'github-dark']`	代码主题
`className`	`string`	—	容器类名

完整API参考请查看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.

插件	包名	用途
代码	`@streamdown/code`	语法高亮（基于Shiki，支持200+种语言）
Mermaid	`@streamdown/mermaid`	图表渲染（流程图、序列图等）
数学公式	`@streamdown/math`	基于KaTeX渲染LaTeX公式（需导入CSS）
中日韩文本	`@streamdown/cjk`	中文/日文/韩文文本支持

数学公式插件需导入CSS：

tsx

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

插件配置详情请查看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

如需更深入的实现细节，请参考以下文档：

references/api.md — 完整属性、类型和接口说明
references/plugins.md — 插件安装、配置和自定义指南
references/styling.md — CSS变量、数据属性、自定义组件、主题示例
references/security.md — 安全加固、链接安全、自定义HTML标签、生产环境配置
references/features.md — 光标动画、静态模式、交互控制、GFM、 memoization、问题排查

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

可从

assets/examples/

目录复制并适配以下示例：

basic-streaming.tsx — 基于Vercel AI SDK的极简AI聊天示例
with-caret.tsx — 带块状光标动画的流式传输示例
full-featured.tsx — 集成所有插件、光标动画、链接安全和交互控制的全功能示例
static-mode.tsx — 博客/文档渲染示例
custom-security.tsx — 针对AI内容的严格安全配置示例

Common Gotchas

常见问题

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

Tailwind样式缺失 — 添加
```
@source
```
指令或在
```
content
```
中包含
```
node_modules/streamdown/dist/*.js
```
数学公式不渲染 — 需导入
```
katex/dist/katex.min.css
```
光标动画不显示 — 需同时设置
```
caret
```
属性和
```
isAnimating={true}
```
流式传输中复制按钮不可用 — 当
```
isAnimating={true}
```
时会自动禁用
弹出链接安全确认弹窗 — 默认启用，可通过
```
linkSafety={{ enabled: false }}
```
禁用
Next.js中出现Shiki警告 — 需显式安装
```
shiki
```
并添加到
```
transpilePackages
```
allowedTags
不生效 — 仅在使用默认rehype插件时有效
数学公式使用
$$
而非
$
— 默认禁用单美元符号以避免与货币符号冲突