# How to Add Mermaid Diagram Support for Flowcharts in the React TipTap Editor

> Add Mermaid diagram support for flowcharts in your React TipTap editor. Render flowcharts as SVG images with this simple configuration guide.

- Repository: [Hung Hoang/reactjs-tiptap-editor](https://github.com/hunghg255/reactjs-tiptap-editor)
- Tags: how-to-guide
- Published: 2026-03-03

---

**Enable the built-in Mermaid extension in your editor configuration and set a flowchart syntax template as the default diagram code to render flowcharts as SVG images.**

The reactjs-tiptap-editor repository includes a native Mermaid extension that supports sequence diagrams, class diagrams, and flowcharts without requiring additional plugins. By registering the extension in the editor store and customizing the starter template, you can seamlessly integrate interactive flowchart creation into your rich-text editing workflow.

## Architecture of the Mermaid Extension

The Mermaid functionality is implemented across modular components in the `src/extensions/Mermaid/` directory, with integration points in the core editor configuration.

### Core Extension Logic

The [`src/extensions/Mermaid/Mermaid.ts`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/extensions/Mermaid/Mermaid.ts) file declares the TipTap node that stores diagrams as image-like blocks. It registers two essential commands: `setMermaid` for inserting new diagrams and `setAlignImageMermaid` for alignment adjustments. This file defines the schema for the `mermaid` node type with attributes for `src`, `alt`, `width`, and `height`.

### UI Components

Three React components handle the user interface:

- **RichTextMermaid** ([`src/extensions/Mermaid/components/RichTextMermaid.tsx`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/extensions/Mermaid/components/RichTextMermaid.tsx)): A modal dialog that lazily loads the `mermaid` library on demand. It provides a live preview of the diagram code via `renderMermaid` and calls `setMermaid` to insert the generated SVG when the user saves changes.

- **EditMermaidBlock** ([`src/extensions/Mermaid/components/EditMermaidBlock.tsx`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/extensions/Mermaid/components/EditMermaidBlock.tsx)): An inline editing interface that appears when users select an existing diagram node. It reuses the rendering logic from `RichTextMermaid` to allow in-place modifications.

- **NodeViewMermaid** ([`src/extensions/Mermaid/components/NodeViewMermaid/NodeViewMermaid.tsx`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/extensions/Mermaid/components/NodeViewMermaid/NodeViewMermaid.tsx)): A React node view that renders the final SVG inside a wrapper `<div class="imageMermaid">` within the editor content, preserving alignment and sizing attributes.

### Configuration Integration

The extension integrates with the editor through these configuration points:

- **Editor Store** ([`src/store/editor.ts`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/store/editor.ts)): Instantiates the TipTap `Editor` and registers all enabled extensions. The Mermaid extension activates when `'mermaid'` appears in the `extensionsNames` array.

- **Type Definitions** ([`src/types.ts`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/types.ts)): Extends the `ExtensionName` union type to include `'mermaid'` as a valid extension identifier.

- **Build Configuration** ([`vite.config.ts`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/vite.config.ts)): Adds the `mermaid` package to the Vite dependency optimization list to enable dynamic imports.

- **Localization** ([`src/locales/en.ts`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/locales/en.ts)): Provides tooltip text for the toolbar button via the `editor.mermaid.tooltip` key.

## Step-by-Step Implementation

Follow these steps to enable flowchart support in your React TipTap editor.

1. **Register the Mermaid Extension**

   Locate the `extensionsNames` array in [`src/store/editor.ts`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/store/editor.ts) and add `'mermaid'` to the list:

   ```typescript
   const extensionsNames = [
     // …other extensions
     'mermaid',
   ];
   ```

   The editor store automatically imports [`src/extensions/Mermaid/Mermaid.ts`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/extensions/Mermaid/Mermaid.ts) and registers the extension with the TipTap editor instance.

2. **Verify Toolbar Button Visibility**

   The toolbar button is defined in the extension's `addOptions().button` method. When the extension is enabled in `extensionsNames`, the button appears automatically in the toolbar with the tooltip text defined in the locale files. No additional markup is required.

3. **Set Flowchart as Default Template**

   Modify the default starter code in [`src/extensions/Mermaid/components/RichTextMermaid.tsx`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/extensions/Mermaid/components/RichTextMermaid.tsx) to use flowchart syntax. Locate the `defaultCode` variable at line 22 and replace it:

   ```typescript
   const defaultCode = `graph LR
     A[Start] --> B{Decision}
     B -->|Yes| C[Result]
     B -->|No| D[Alternative]`;
   ```

   This provides users with a ready-made flowchart skeleton when they open the Mermaid dialog.

4. **Configure Rendering Options (Optional)**

   Customize the Mermaid initialization in [`RichTextMermaid.tsx`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/RichTextMermaid.tsx) by adjusting the `mermaidInit` function (lines 59-67). For dark-mode-aware flowcharts:

   ```typescript
   mermaidInstance.initialize({
     darkMode: true,
     theme: 'dark',
     startOnLoad: false,
     fontSize: 13,
   });
   ```

## How Flowchart Rendering Works

When a user clicks the **Mermaid** toolbar button, the `RichTextMermaid` component opens a modal dialog. The component lazily imports the `mermaid` library via `import('mermaid')` and initializes it with the configured options.

As the user types Mermaid code, the `renderMermaid` function calls `mermaidInstance.render`, which returns an SVG string. The component displays this live via `dangerouslySetInnerHTML`. When the user clicks **Save changes**, the SVG is serialized to a data URL (or uploaded if an `upload` function is configured) and inserted into the document via the `setMermaid` command.

The resulting `mermaid` node stores the SVG source and original diagram code, which `NodeViewMermaid` renders as an `<img>` tag inside the editor content. To edit an existing flowchart, users select the diagram to trigger `RichTextBubbleMermaid` ([`src/components/Bubble/RichTextBubbleMermaid.tsx`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/components/Bubble/RichTextBubbleMermaid.tsx)), which launches `EditMermaidBlock` for inline modifications.

## Practical Code Examples

### Adding the Extension Programmatically

Import the Mermaid extension directly when constructing your editor:

```typescript
import { Editor } from '@tiptap/react';
import { Mermaid } from 'reactjs-tiptap-editor/mermaid';

const editor = new Editor({
  extensions: [
    // other extensions …
    Mermaid,
  ],
});

```

### Using the setMermaid Command Directly

Insert a flowchart programmatically using the command chain:

```typescript
editor
  .chain()
  .focus()
  .setMermaid({
    src: 'data:image/svg+xml;base64,…',   // generated SVG data URL
    alt: encodeURIComponent('graph LR\nA-->B'),
    width: 500,
    height: 300,
  })
  .run();

```

### Custom Default Flowchart Template

Replace the generic graph starter with a specific flowchart pattern in [`RichTextMermaid.tsx`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/RichTextMermaid.tsx):

```typescript
// src/extensions/Mermaid/components/RichTextMermaid.tsx
const defaultCode = `graph TD
    A[Start] --> B(Is it working?)
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> E[Fix Issue]
    E --> B`;

```

## Summary

- **Enable the extension** by adding `'mermaid'` to the `extensionsNames` array in [`src/store/editor.ts`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/store/editor.ts).
- **Customize the starter template** in [`src/extensions/Mermaid/components/RichTextMermaid.tsx`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/extensions/Mermaid/components/RichTextMermaid.tsx) at line 22 to use `graph LR`, `graph TD`, or other flowchart-specific syntax.
- **Render flowcharts** using the built-in `setMermaid` command, which stores the SVG output as a node attribute.
- **Edit inline** via `EditMermaidBlock`, which provides the same live preview capabilities as the creation dialog.
- **Configure themes** by modifying the `mermaidInit` options to support dark mode or custom color schemes.

## Frequently Asked Questions

### How do I change the default flowchart direction from top-down to left-to-right?

Edit the `defaultCode` variable in [`src/extensions/Mermaid/components/RichTextMermaid.tsx`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/extensions/Mermaid/components/RichTextMermaid.tsx) at line 22. Replace `graph TB` (top-bottom) or `graph TD` (top-down) with `graph LR` (left-right) in the template string. This changes the starter code for all new diagrams while preserving existing flowcharts.

### Can I use custom themes for my flowcharts?

Yes. Modify the `mermaidInit` function in [`src/extensions/Mermaid/components/RichTextMermaid.tsx`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/extensions/Mermaid/components/RichTextMermaid.tsx) (lines 59-67) to include theme options. Set the `theme` property to values like `'dark'`, `'forest'`, or `'neutral'` in the initialization object passed to `mermaidInstance.initialize()`.

### Where is the Mermaid library actually loaded?

The library is dynamically imported on demand. In [`src/extensions/Mermaid/components/RichTextMermaid.tsx`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/src/extensions/Mermaid/components/RichTextMermaid.tsx), the code uses `import('mermaid')` to load the package only when the user opens the Mermaid dialog. This prevents the library from bloating the initial bundle size. The [`vite.config.ts`](https://github.com/hunghg255/reactjs-tiptap-editor/blob/main/vite.config.ts) file ensures Vite pre-bundles the dependency for faster dynamic imports.

### How do I programmatically insert a flowchart without using the toolbar?

Use the `setMermaid` command provided by the extension. Chain `editor.chain().focus().setMermaid({ src, alt, width, height }).run()`, where `src` is a base64-encoded SVG data URL and `alt` contains the URL-encoded Mermaid source code. This command creates a `mermaid` node type with the specified attributes.