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

#react #mermaid #vite #webdev

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