🧠 TL;DR — I couldn’t find a working React library for Mermaid diagrams, so I built my own — simple, typed, and customizable. Here’s how it works and how you can use it.
1️⃣ The Problem: Rendering Mermaid in React is not smooth
If you’ve ever tried to render Mermaid diagrams inside a React app, you know the pain.
Recently, I faced the same challenge — and realized most existing libraries either don’t work well or are abandoned.
The current React-specific packages are either too old, poorly documented, or simply not working anymore.
Sure, you can always use plain Mermaid.js directly — but that means writing a bunch of boilerplate setup code just to render a simple diagram.
That’s extra work every time you want to add or update one.
What I Noticed While Researching.
- Many libraries are outdated and unmaintained.
- Some break during render or don’t handle updates properly.
- Most have poor documentation and very few examples.
All this slowed down my project — and sparked an idea:
What if I build a React library that just works out of the box?
Introducing My Library — Render Mermaid in React with Ease
So I rolled up my sleeves and built a lightweight React library that lets you render Mermaid code with minimal setup.
It supports two main approaches, depending on how you like to work:
1. Component-based Approach
This is the easiest way to get started.
Just import and use the provided React component — no extra setup required.
✅ Features:
- Plug-and-play usage
- Fully typed props (TypeScript support)
- Customizable theme & style
- Built-in error states for syntax/render issues
- Copy-code + download-as-SVG support
import RenderMermaid from "react-x-mermaid";
function App() {
const d1 = `
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
`;
return (
<div className="app">
<RenderMermaid mermaidCode={d1} mermaidConfig={{ theme: "dark" }} />
</div>
);
}
export default App;
2. Hook-based Approach (For Advanced Use Cases)
If you want full control, the library also provides a custom hook.
It gives you access to the rendered SVG and state, so you can build your own UI around it.
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 <pre> and <code> tags if you need as a fallback.
return <div className="mermaid__error">{error}</div>;
}
return <div className="mermaid-renderer" ref={ref} />;
}
export default AdvanceMermaidRenderer;
✅ Perfect for:
- Integrating Mermaid inside markdown renderers
- Custom toolbars, editors, or documentation apps
🚀_ Why This Matters_
If you’re building documentation tools, internal dashboards, or markdown editors, Mermaid diagrams are incredibly useful for visualizing flows and systems.
Having a reliable React wrapper saves hours of setup and debugging.
🧠 Behind the Scenes
- Written in TypeScript
- Uses Mermaid v11+
- Handles async rendering and cleanup
- Tested across SSR and client-only setups
🙌 Try It Yourself
Install it in seconds:
npm install react-x-mermaid mermaid
# or
yarn add react-x-mermaid mermaid
Docs and examples: https://www.npmjs.com/package/react-x-mermaid
💬 Wrap-up
If you’ve struggled to render Mermaid in React, this library should make it a breeze.
Give it a try — and if you hit any edge cases, drop them in the comments.
I’d love to see how you use it in your projects!
Top comments (2)
Hey @navdeepm20 ,
thanks for the package, exactly what I was looking for ( as a replacement for my custom implementation ).
Any plans to make the github repo public? the github.com/navdeepm20/react-x-mermaid link ( via npmjs ) results in an 404 :-/
Nice work! The component and hook APIs, TS types, and error handling make Mermaid in React painless. Docs link is handy too.