@assistant-ui/react-streamdown

@assistant-ui/react-streamdown

Streamdown-based markdown rendering for assistant-ui. An alternative to @assistant-ui/react-markdown with built-in syntax highlighting, math, and diagram support.

When to Use

Package	Best For
@assistant-ui/react-markdown	Lightweight, bring-your-own syntax highlighter
@assistant-ui/react-streamdown	Feature-rich with built-in Shiki, KaTeX, Mermaid

Installation

npm install @assistant-ui/react-streamdown streamdown

For additional features, install the optional plugins:

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

Usage

Basic

import { StreamdownTextPrimitive } from "@assistant-ui/react-streamdown";

// Inside a MessagePartText component
<StreamdownTextPrimitive />

With Plugins (Recommended)

import { StreamdownTextPrimitive } from "@assistant-ui/react-streamdown";
import { code } from "@streamdown/code";
import { math } from "@streamdown/math";
import { mermaid } from "@streamdown/mermaid";
import "katex/dist/katex.min.css";

<StreamdownTextPrimitive
  plugins={{ code, math, mermaid }}
  shikiTheme={["github-light", "github-dark"]}
/>

Migration from react-markdown

If you're migrating from @assistant-ui/react-markdown, you can use the compatibility API:

import { StreamdownTextPrimitive } from "@assistant-ui/react-streamdown";

// Your existing SyntaxHighlighter component still works
<StreamdownTextPrimitive
  components={{
    SyntaxHighlighter: MySyntaxHighlighter,
    CodeHeader: MyCodeHeader,
  }}
  componentsByLanguage={{
    mermaid: { SyntaxHighlighter: MermaidRenderer }
  }}
/>

Props

Prop	Type	Description
mode	"streaming" | "static"	Rendering mode. Default: "streaming"
plugins	PluginConfig	Streamdown plugins (code, math, mermaid, cjk)
shikiTheme	[string, string]	Light and dark theme for Shiki
components	object	Custom components including SyntaxHighlighter and CodeHeader
componentsByLanguage	object	Language-specific component overrides
preprocess	(text: string) => string	Text preprocessing function
controls	boolean | object	Enable/disable UI controls for code blocks and tables
containerProps	object	Props for the container div
containerClassName	string	Class name for the container
remarkRehypeOptions	object	Options passed to remark-rehype during processing
BlockComponent	React.ComponentType	Custom component for rendering blocks
parseMarkdownIntoBlocksFn	(md: string) => string[]	Custom block parsing function
remend	object	Incomplete markdown auto-completion config
linkSafety	object	Link safety confirmation config
mermaid	object	Mermaid diagram rendering config
allowedTags	object	HTML tags whitelist

Differences from react-markdown

• Streaming optimization: Uses block-based rendering and remend for better streaming performance
• Built-in highlighting: Shiki is integrated via @streamdown/code plugin
• No smooth prop: Streaming animation is handled by streamdown's mode and isAnimating
• Auto isAnimating: Automatically detects streaming state from message context

Advanced Usage

Custom Block Rendering

Use BlockComponent to customize how individual markdown blocks are rendered:

<StreamdownTextPrimitive
  BlockComponent={({ content, index }) => (
    <div key={index} className="my-block">
      {/* Custom block rendering */}
    </div>
  )}
/>

Custom Block Parsing

Override the default block splitting logic:

<StreamdownTextPrimitive
  parseMarkdownIntoBlocksFn={(markdown) => markdown.split(/\n{2,}/)}
/>

Using Hooks

import {
  useIsStreamdownCodeBlock,
  useStreamdownPreProps,
} from "@assistant-ui/react-streamdown";

// Inside a code component
function MyCodeComponent() {
  const isCodeBlock = useIsStreamdownCodeBlock();
  const preProps = useStreamdownPreProps();

  if (!isCodeBlock) {
    return <code className="inline-code">...</code>;
  }

  return <pre {...preProps}>...</pre>;
}

Performance Best Practices

• Use memoized components: Custom SyntaxHighlighter and CodeHeader components should be memoized to avoid unnecessary re-renders.

• Avoid inline function props: Define preprocess, parseMarkdownIntoBlocksFn, and other callbacks outside the render function or wrap them in useCallback.

• Plugin configuration: Pass plugin objects by reference (not inline) to prevent recreation on each render.

// Good
const plugins = useMemo(() => ({ code, math }), []);
<StreamdownTextPrimitive plugins={plugins} />

// Avoid
<StreamdownTextPrimitive plugins={{ code, math }} />

License

MIT