How I Rendered Mermaid Diagrams in React (and Built a Library for It)

🧠 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:

1. Integrating Mermaid inside markdown renderers
2. 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

1. Written in TypeScript
2. Uses Mermaid v11+
3. Handles async rendering and cleanup
4. 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!

Comments

[Ethan Anderson]

Nice work! The component and hook APIs, TS types, and error handling make Mermaid in React painless. Docs link is handy too.