A small, lightweight React wrapper component and hook for rendering Mermaid diagrams from Mermaid syntax strings.
npm install react-x-mermaidMermaid React component that accepts a Mermaid diagram string.
useMermaid hook for programmatic control and rendering.
bash
npm install react-x-mermaid mermaid
or
yarn add react-x-mermaid mermaid
`
Peer dependencies:
Quick Start
Render a diagram using the Mermaid component:
`tsx
import "./App.css";
import RenderMermaid from "react-x-mermaid";
function App() {
const d1 =
;
return (
);
}
export default App;
`
Or use the useMermaid hook for manual rendering and lifecycle control:
`tsx
import { useMermaid } from "react-x-mermaid";
function AdvanceMermaidRenderer({ chart }: { chart: string }) {
// hook also gives you svg along with ref and error which it generate which you can use to download and save locally if required
const { ref, error } = useMermaid(chart, {
theme: "dark", // mermaid config
});
if (error) {
// show error or render code in and tags if you need as a fallback.
return {error};
}
return ;
}
export default AdvanceMermaidRenderer;
`
`tsx
// App.tsx;
import "./App.css";
import AdvanceMermaidRenderer from "./AdvanceMermaidRenderer";
function App() {
const d1 =
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
;
return (
);
}
export default App;
`
API
$3
A React hook that provides programmatic control over Mermaid diagram rendering with error handling and lifecycle management.
#### Signature
`typescript
useMermaid(chart: string, config?: MermaidConfig) => {
ref: RefObject;
svg: string;
error: string | null;
}
`
#### Parameters
| Parameter | Type | Required | Description |
| --------- | --------------- | -------- | ------------------------------------------------------------------- |
| chart | string | Yes | The Mermaid diagram syntax string to render |
| config | MermaidConfig | No | Optional Mermaid configuration object (defaults to internal config) |
#### Returns
| Property | Type | Description |
| -------- | ----------------------------------- | ------------------------------------------------------------------------------------- |
| ref | RefObject | React ref to attach to a DOM element where the diagram will be rendered |
| svg | string | The rendered SVG string of the diagram (useful for downloading or further processing) |
| error | string \| null | Error message if diagram rendering fails, null if successful |
$3
Basic Usage:
`tsx
import { useMermaid } from "react-x-mermaid";
function MyDiagram() {
const chart =
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
;
const { ref, svg, error } = useMermaid(chart);
if (error) {
return Error: {error};
}
return ;
}
`
With Custom Configuration:
`tsx
import { useMermaid } from "react-x-mermaid";
function ThemedDiagram() {
const chart = "graph TD; A-->B;";
const { ref, error } = useMermaid(chart, {
theme: "dark",
flowchart: {
useMaxWidth: true,
htmlLabels: true,
},
});
return ;
}
`
Using SVG for Download:
`tsx
import { useMermaid } from "react-x-mermaid";
function DownloadableDiagram() {
const chart = "graph TD; A-->B;";
const { ref, svg, error } = useMermaid(chart);
const downloadSVG = () => {
if (svg) {
const blob = new Blob([svg], { type: "image/svg+xml" });
const url = URL.createObjectURL(blob);
const a = document.createElement("a");
a.href = url;
a.download = "diagram.svg";
a.click();
}
};
return (
{svg && }
);
}
`
#### Behavior
- Automatic Re-rendering: The diagram automatically re-renders when the chart or config parameters change
- Error Handling: Catches and exposes rendering errors through the error property
- DOM Integration: Automatically injects the rendered SVG into the DOM element referenced by ref
- Async Rendering: Uses Mermaid's async rendering API for better performance
#### Error Handling
The hook gracefully handles various error scenarios:
- Invalid Mermaid syntax
- Configuration errors
- Rendering failures
When an error occurs, the error property contains the error message, and the svg property is cleared.
$3
A React component that renders Mermaid diagrams with built-in error handling, copy functionality, and SVG download capabilities.
#### Signature
`typescript
interface RenderMermaidProps {
mermaidCode: string;
errorComponent?: React.ComponentType<{ error: string; mermaidCode: string }>;
disableDownload?: boolean;
disableCopy?: boolean;
downloadComponent?: React.ComponentType<{ onClick: () => void }>;
copyComponent?: React.ComponentType<{ onClick: () => void }>;
mermaidConfig?: MermaidConfig;
renderCode?: React.ComponentType<{ code: string }>;
}
const Mermaid: React.FC = (props) => JSX.Element;
`
#### Props
| Prop | Type | Required | Default | Description |
| ------------------- | ------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------- |
| mermaidCode | string | Yes | - | The Mermaid diagram syntax string to render |
| errorComponent | React.ComponentType<{ error: string; mermaidCode: string }> | No | - | Custom component to render when diagram fails to load |
| disableDownload | boolean | No | false | When true, hides the download SVG button |
| disableCopy | boolean | No | false | When true, hides the copy code button |
| downloadComponent | React.ComponentType<{ onClick: () => void }> | No | - | Custom component for the download button (replaces default button) |
| copyComponent | React.ComponentType<{ onClick: () => void }> | No | - | Custom component for the copy button (replaces default button) |
| mermaidConfig | MermaidConfig | No | - | Mermaid configuration object passed to mermaid.initialize() |
| renderCode | React.ComponentType<{ code: string }> | No | - | Custom component for rendering the raw Mermaid code (used in error state) |
#### Features
- Automatic Rendering: Renders Mermaid diagrams from syntax strings
- Error Handling: Gracefully handles rendering errors with fallback UI
- Copy Functionality: Built-in copy-to-clipboard for the Mermaid code
- SVG Download: Download rendered diagrams as SVG files
- Customizable UI: Replace default buttons and error components with custom ones
- Memory Management: Properly cleans up resources on unmount
- Memoized: Uses React.memo for performance optimization
#### Usage Examples
Basic Usage:
`tsx
import Mermaid from "react-x-mermaid";
function App() {
const diagram =
graph TD;
A[Start] --> B{Decision};
B -->|Yes| C[Action 1];
B -->|No| D[Action 2];
C --> E[End];
D --> E;
;
return ;
}
`
With Custom Configuration:
`tsx
import Mermaid from "react-x-mermaid";
function ThemedDiagram() {
const diagram = "graph TD; A-->B;";
return (
mermaidCode={diagram}
mermaidConfig={{
theme: "dark",
flowchart: {
useMaxWidth: true,
htmlLabels: true,
},
}}
/>
);
}
`
With Disabled Actions:
`tsx
import Mermaid from "react-x-mermaid";
function SimpleDiagram() {
const diagram = "graph TD; A-->B;";
return (
);
}
`
With Custom Error Component:
`tsx
import Mermaid from "react-x-mermaid";
function CustomErrorComponent({ error, mermaidCode }) {
return (
Diagram Error
{error}
View Code
{mermaidCode}
);
}
function DiagramWithCustomError() {
const diagram = "invalid mermaid syntax";
return (
);
}
`
With Custom Action Buttons:
`tsx
import Mermaid from "react-x-mermaid";
function CustomCopyButton({ onClick }) {
return (
);
}
function CustomDownloadButton({ onClick }) {
return (
);
}
function DiagramWithCustomButtons() {
const diagram = "graph TD; A-->B;";
return (
mermaidCode={diagram}
copyComponent={CustomCopyButton}
downloadComponent={CustomDownloadButton}
/>
);
}
`
With Custom Code Renderer:
`tsx
import Mermaid from "react-x-mermaid";
function SyntaxHighlightedCode({ code }) {
return (
Mermaid Code:
{code}
);
}
function DiagramWithCustomCodeRenderer() {
const diagram = "graph TD; A-->B;";
return ;
}
`
#### CSS Classes
The component applies the following CSS classes that you can style:
- .mermaid-renderer - Main container
- .mermaid-actions - Container for action buttons
- .mermaid-action-button - Default action buttons
- .btn-copy - Copy button
- .btn-download - Download button
- .mermaid-diagram - Container for the rendered diagram
- .mermaid-error-container - Error state container
- .mermaid-code-renderer - Default code renderer
#### Behavior
- Automatic Re-rendering: Re-renders when mermaidCode or mermaidConfig changes
- Error Recovery: Shows error UI with code fallback when rendering fails
- Memory Management: Cleans up SVG content on unmount to prevent memory leaks
- Clipboard Integration: Uses navigator.clipboard.writeText()` for copy functionality
- File Download: Generates and downloads SVG files with proper MIME type
Contributing
Contributions are welcome. Please open issues or PRs for bugs and improvements. Keep changes small and add tests for new behavior.
License
MIT
Keywords
react react-componentmuimaterial-uimaterial design