@streamdown/mermaid
The @streamdown/mermaid plugin renders Mermaid diagrams including flowcharts, sequence diagrams, state diagrams, and more using text-based syntax. Each diagram includes interactive controls for fullscreen viewing, downloading, and copying.
- Interactive controls (fullscreen, download, copy)
- Custom theming support
- Error handling with retry
Install
Tailwind CSS
Tailwind v4
Add the following @source directive to your globals.css or main CSS file:
The path must be relative from your CSS file to the node_modules folder containing @streamdown/mermaid. In a monorepo, adjust the number of ../ segments to reach the root node_modules.
Tailwind v3
Add @streamdown/mermaid to your content array in tailwind.config.js:
In a monorepo, adjust the path to reach the root node_modules:
Usage
Without the mermaid plugin, mermaid code blocks render as plain code instead of diagrams.
Basic Usage
Create Mermaid diagrams using code blocks with the mermaid language identifier:
Streamdown renders the diagram as an interactive SVG with controls.
Diagram Types
Flowcharts
Create flowcharts to visualize processes and workflows:
Node Shapes:
[text]- Rectangle(text)- Rounded rectangle{text}- Rhombus (decision)((text))- Circle[[text]]- Subroutine shape
Direction:
graph TD- Top to bottomgraph LR- Left to rightgraph BT- Bottom to topgraph RL- Right to left
Sequence Diagrams
Visualize interactions between different actors or systems:
Arrow Types:
->- Solid line-->- Dotted line->>- Solid arrow-->>- Dotted arrow
State Diagrams
Model state machines and state transitions:
Class Diagrams
Document object-oriented designs:
Pie Charts
Display proportional data:
Gantt Charts
Plan and track project timelines:
Entity Relationship Diagrams
Model database relationships:
Git Graphs
Visualize Git workflows:
Configuration
Default Settings
The Mermaid plugin uses these defaults:
startOnLoad: false- Diagrams render on demandtheme: "default"- Default plugin themesecurityLevel: "strict"- Secure renderingfontFamily: "monospace"- Consistent code-like typographysuppressErrorRendering: true- Prevents partial renders on errors
By default, the plugin provides its own theme and font settings for backward compatibility. To use Mermaid's native theme and font defaults instead, enable the useMermaidDefaults option when creating the plugin.
Theme Customization
Customize the Mermaid theme using the mermaid.config prop:
Available Themes
Mermaid includes several built-in themes:
default- Classic Mermaid themedark- Dark mode optimizedforest- Green tonesneutral- Minimal stylingbase- Clean, modern style
Example:
Advanced Configuration
Customize specific diagram types:
Factory Function
For advanced configuration, use createMermaidPlugin:
When useMermaidDefaults is enabled, the plugin does not specify theme or fontFamily. You can still provide either property through config or the configuration passed to getMermaid().
Error Handling
Custom Error Component
When Mermaid diagrams fail to render due to invalid syntax, you can provide a custom error component. This is useful for production environments where you want to control the user experience.
The error component receives three props:
- error (
string) - The error message from Mermaid - chart (
string) - The original Mermaid diagram code - retry (
() => void) - Function to retry rendering the diagram - cause (
unknown, optional) - The original value thrown by Mermaid. Its shape depends on the parser: Jison errors expose ahash(token, line, expected tokens), while Langium errors do not, so check the shape before reading properties.
Example: Logging Errors
Interactive Controls
Each Mermaid diagram includes interactive controls:
Fullscreen Mode
Click the fullscreen button to view the diagram in an overlay with a dark background. This is useful for complex diagrams.
Download
Download the diagram as SVG, PNG, or Mermaid source. By default files are named diagram.svg, diagram.png, and diagram.mmd. Pass download: { filename: "flowchart" } to use a custom base name.
Copy
Copy the diagram source to your clipboard for pasting into other applications. Pass callbacks through controls.mermaid.copy to react to success or failure without replacing the default button:
Customizing Controls
You can customize which controls are shown:
Or disable specific controls:
Or disable all Mermaid controls:
Streaming Considerations
Initial Render
When Mermaid diagrams are first streamed in, they appear as code blocks until the diagram syntax is complete. Streamdown's parser ensures the code block is properly formatted during streaming.
Avoid Continuous Re-rendering
Mermaid diagrams are expensive to render. During streaming, you don't want to re-render the diagram on every chunk — that would be slow and cause flickering. Use the useIsCodeFenceIncomplete hook to wait until the code block is complete before rendering:
This shows a placeholder while the code block is streaming, then renders the Mermaid diagram only once the closing ``` is received — without waiting for the entire markdown stream to finish.
Disable Interactions During Streaming
Use the isAnimating prop to disable interactive controls while content is streaming:
This prevents users from interacting with incomplete diagrams.
Syntax Reference
Flowchart Links
Sequence Diagram Actors
Styling Nodes
Subgraphs
Best Practices
Keep Diagrams Focused
Break complex diagrams into smaller, focused visualizations:
Add Context
Provide descriptions for your diagrams:
Use Descriptive Labels
Make your diagrams self-documenting:
Choose the Right Diagram Type
Select the diagram type that best represents your information:
- Flowchart - Processes, algorithms, workflows
- Sequence - API interactions, communication flows
- State - Lifecycle, state machines
- Class - Object relationships, architecture
- ER - Database schemas
- Gantt - Project timelines
- Pie/Bar - Statistical data
Common Issues
Diagram Not Rendering
- Verify the Mermaid plugin is passed to Streamdown
- Verify the syntax is correct (check Mermaid Live Editor)
- Ensure the code block uses
```mermaid - Check browser console for JavaScript errors
Performance with Large Diagrams
Large diagrams may take time to render. Consider:
- Breaking into smaller diagrams
- Simplifying node relationships
- Using subgraphs for organization
- Lazy loading diagram-heavy pages
Theme Not Applying
- Verify
mermaid.configis properly passed - Check that theme name is spelled correctly
- Ensure custom theme variables are valid
Plugin Interface
The Mermaid plugin implements the DiagramPlugin interface:
The language property indicates which code block language triggers diagram rendering.
Resources
- Mermaid Documentation - Official docs
- Mermaid Live Editor - Test diagrams online
- Syntax Reference - Complete syntax guide
- Mermaid Examples - Gallery of examples
Related Features
- Code Blocks - Syntax highlighting for other code
- GitHub Flavored Markdown - Extended Markdown features
- Typography - Text styling around diagrams
- Unterminated Block Parsing - How streaming works with Mermaid