Streamdown

Streamdown is a React markdown-rendering component purpose-built for the failure modes that show up when you render text as it streams token-by-token from a large language model. Ordinary markdown renderers choke on unterminated code fences, half-written tables, and dangling list markers because they assume a complete, well-formed document; Streamdown instead repairs and parses incomplete markdown incrementally, block by block, so the UI never flashes broken formatting while a response is still arriving.

It ships as a near drop-in swap for react-markdown, adding GitHub Flavored Markdown, KaTeX math, Mermaid diagrams, and Shiki-powered code highlighting out of the box, plus security-first sanitization via rehype-harden. It powers the Message component in Vercel’s AI Elements and AI SDK ecosystem but works standalone in any React app that needs to render streaming AI output.

What You Get

• A <Streamdown> React component that is a near drop-in replacement for react-markdown, accepting the same components, remarkPlugins, and rehypePlugins props
• Streaming-safe incremental parsing that repairs unterminated code fences, tables, and lists before each render so output never flashes broken formatting
• Built-in GitHub Flavored Markdown (tables, task lists, strikethrough) via remark-gfm
• Optional plugin packages for KaTeX math, Mermaid diagram rendering, Shiki code highlighting with copy/download controls, and CJK-friendly text handling
• Security-first sanitization by default via rehype-sanitize and rehype-harden, with configurable allowed tags and a link-safety confirmation modal
• Fine-grained controls for animated character-by-character reveal, RTL/LTR text direction detection, i18n string overrides, and a Tailwind class prefix option

Common Use Cases

• Rendering assistant responses in an LLM chat UI while the response is still streaming from the model
• Displaying AI-generated content that mixes prose, code blocks, tables, and diagrams without waiting for the full response to complete
• Building chat and copilot interfaces on top of the Vercel AI SDK’s useChat hook, where Streamdown is the standard rendering layer for message parts

Under The Hood

Architecture Streamdown’s Streamdown component (packages/streamdown/index.tsx) splits incoming markdown into independently-memoized Block components via parseMarkdownIntoBlocks (lib/parse-blocks.tsx), so only the last, still-changing block re-renders during a stream while earlier blocks stay frozen by React’s memo. Before parsing, the remend sibling package rewrites unterminated markdown constructs (open fences, dangling table rows) so the underlying unified/remark/rehype pipeline never sees invalid input. A single combined StreamdownContext carries theme, controls, and mode state to avoid deep provider nesting, and an internal PluginContext lets optional @streamdown/* packages (math, mermaid, code, cjk) register their own remark/rehype plugins without the core package depending on them directly.

Tech Stack The package is TypeScript-first, targeting React 18/19 as peer dependencies, and is built on the unified ecosystem (remark-parse, remark-gfm, remark-rehype, rehype-sanitize, rehype-raw) with marked’s Lexer used specifically for block-boundary detection. Sanitization is hardened via rehype-harden, and styling uses clsx + tailwind-merge with a custom createCn prefixing helper so consumers on Tailwind v4’s prefix() feature aren’t broken. It’s published from a Turborepo/pnpm monorepo (packages/streamdown plus sibling remend, @streamdown/code, @streamdown/math, @streamdown/mermaid, @streamdown/cjk) built with tsup.

Code Quality The streamdown package alone has 75 test files under __tests__/ covering individual concerns (footnotes, RTL support, code-block hydration, KaTeX lazy-loading, link safety, mermaid pan/zoom, table CSV export, etc.), plus a __benchmarks__/ suite comparing performance directly against react-markdown. CI (.github/workflows) runs pnpm test and pnpm check (Biome/Ultracite lint + format) on every push. Source comments frequently explain non-obvious performance and correctness decisions (e.g. why block keys are index-based rather than content-hash-based, why a regex was changed to fix a footnote-matching bug), indicating an actively maintained, defect-aware codebase.

API Design The component intentionally mirrors react-markdown’s prop surface (components, remarkPlugins, rehypePlugins) so migration is close to a one-line import swap, while layering streaming-specific props (mode, isAnimating, parseIncompleteMarkdown, animated) with sensible defaults (mode="streaming", sanitization on, controls on). Optional capabilities (math, mermaid, code highlighting, CJK handling) are opt-in via a plugins prop backed by separate installable packages, keeping the core bundle lean for consumers who don’t need them.