Mermaid Diagrams
Render interactive diagrams and flowcharts using Mermaid syntax with automatic theme detection and lazy loading.
Overview
The ProseMermaid component renders diagrams using Mermaid, a popular JavaScript-based diagramming and charting tool. It supports flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, and more.
- Automatic Theme Detection - Switches between light/dark themes
- Lazy Loading - Only renders when scrolled into view for better performance
- Error Handling - Shows friendly error messages if diagram syntax is invalid
- Loading State - Displays spinner while rendering
Basic Usage
Use code blocks with the mermaid language:
Flowcharts
Top to Bottom
Left to Right
With Styling
Sequence Diagrams
API Request Flow
Authentication Flow
Loops and Notes
Class Diagrams
Simple Class Structure
Full Example with Relationships
State Diagrams
Order Status
Complex State Machine
Entity Relationship Diagrams
Database Schema
Pie Charts
Simple Distribution
Technology Stack Usage
Gantt Charts
Project Timeline
Git Graph
Branch Strategy
Journey Diagrams
User Experience
Quadrant Chart
Feature Prioritization
Error Handling
If there's an error in your diagram syntax, you'll see a helpful error message:
Code Fence Meta Options
You can add options to the code fence:
```mermaid
graph TD
A --> B
```
Common Use Cases
Documentation
Use flowcharts to explain processes:
Architecture Diagrams
Show system components:
Process Flows
Document workflows:
Performance
The component uses:
- Intersection Observer - Only renders when scrolled into view
- Lazy Loading - Improves initial page load time
- Smart Re-rendering - Only re-renders on theme or code changes
Theme Switching
The component automatically detects your color mode and applies the appropriate Mermaid theme:
- Light Mode - Uses default Mermaid theme
- Dark Mode - Uses dark Mermaid theme
When you switch themes, diagrams automatically re-render with the new theme.
Configuration
The Mermaid instance is configured in app/plugins/mermaid.client.ts:
Mermaid Plugin Configuration
import mermaid from "mermaid";
import type { MermaidConfig } from "mermaid";
export default defineNuxtPlugin(() => {
/**
* Mermaid initialization configuration
*/
const mermaidInitConfig = {
startOnLoad: false,
themeVariables: {
fontFamily: "var(--font-sans)",
fontSize: "13px",
},
flowchart: {
curve: "basis",
useMaxWidth: true,
},
sequence: {
actorMargin: 50,
showSequenceNumbers: false,
},
suppressErrorRendering: true,
} as MermaidConfig;
/**
* Initialize Mermaid with the specified configuration
*/
mermaid.initialize(mermaidInitConfig);
return {
provide: {
mermaidInstance: mermaid,
mermaidInitConfig,
},
};
});
You can customize these settings based on your needs.
Best Practices
- Keep diagrams simple and focused on one concept
- Use descriptive labels for better understanding
- Add notes to explain complex parts
- Use subgraphs to group related nodes
- Choose appropriate diagram types for your content
- Test your diagrams for syntax errors before publishing
- Use styling sparingly to highlight important elements