---
title: @streamdown/mermaid
description: Render Mermaid diagrams including flowcharts, sequence diagrams, and more.
type: reference
summary: Client-side Mermaid rendering with interactive controls, theming, and error handling.
prerequisites:
  - /docs/plugins
related:
  - /docs/code-blocks
  - /docs/typography
---

# @streamdown/mermaid



The `@streamdown/mermaid` plugin renders [Mermaid](https://mermaid.js.org/) diagrams including flowcharts, sequence diagrams, state diagrams, and more using text-based syntax. Each diagram includes interactive controls for fullscreen viewing, downloading, and copying.

* Interactive controls (fullscreen, download, copy)
* Custom theming support
* Error handling with retry

## Install

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @streamdown/mermaid
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @streamdown/mermaid
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @streamdown/mermaid
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @streamdown/mermaid
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Tailwind CSS

### Tailwind v4

Add the following `@source` directive to your `globals.css` or main CSS file:

```css title="globals.css"
@source "../node_modules/@streamdown/mermaid/dist/*.js";
```

The path must be relative from your CSS file to the `node_modules` folder containing `@streamdown/mermaid`. In a monorepo, adjust the number of `../` segments to reach the root `node_modules`.

### Tailwind v3

Add `@streamdown/mermaid` to your `content` array in `tailwind.config.js`:

```js title="tailwind.config.js"
module.exports = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
    "./node_modules/@streamdown/mermaid/dist/*.js",
  ],
  // ... rest of your config
};
```

In a monorepo, adjust the path to reach the root `node_modules`:

```js title="tailwind.config.js"
module.exports = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
    "../../node_modules/@streamdown/mermaid/dist/*.js",
  ],
  // ... rest of your config
};
```

## Usage

```tsx title="chat.tsx" lineNumbers
import { mermaid } from '@streamdown/mermaid';

<Streamdown plugins={{ mermaid }}>
  {markdown}
</Streamdown>
```

Without the mermaid plugin, mermaid code blocks render as plain code instead of diagrams.

## Basic Usage

Create Mermaid diagrams using code blocks with the `mermaid` language identifier:

````markdown
```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Success]
    B -->|No| D[Try Again]
    D --> B
```
````

Streamdown renders the diagram as an interactive SVG with controls.

## Diagram Types

### Flowcharts

Create flowcharts to visualize processes and workflows:

````markdown
```mermaid
graph TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[Car]
```
````

**Node Shapes:**

* `[text]` - Rectangle
* `(text)` - Rounded rectangle
* `{text}` - Rhombus (decision)
* `((text))` - Circle
* `[[text]]` - Subroutine shape

**Direction:**

* `graph TD` - Top to bottom
* `graph LR` - Left to right
* `graph BT` - Bottom to top
* `graph RL` - Right to left

### Sequence Diagrams

Visualize interactions between different actors or systems:

````markdown
```mermaid
sequenceDiagram
    participant User
    participant Browser
    participant Server
    participant Database

    User->>Browser: Enter URL
    Browser->>Server: HTTP Request
    Server->>Database: Query data
    Database-->>Server: Return results
    Server-->>Browser: HTTP Response
    Browser-->>User: Display page
```
````

**Arrow Types:**

* `->` - Solid line
* `-->` - Dotted line
* `->>` - Solid arrow
* `-->>` - Dotted arrow

### State Diagrams

Model state machines and state transitions:

````markdown
```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Loading: start
    Loading --> Success: data received
    Loading --> Error: failed
    Success --> Idle: reset
    Error --> Loading: retry
    Success --> [*]
```
````

### Class Diagrams

Document object-oriented designs:

````markdown
```mermaid
classDiagram
    class User {
        +String name
        +String email
        +login()
        +logout()
    }
    class Post {
        +String title
        +String content
        +Date createdAt
        +publish()
    }
    User "1" --> "*" Post: creates
```
````

### Pie Charts

Display proportional data:

````markdown
```mermaid
pie title Project Time Distribution
    "Development" : 45
    "Testing" : 20
    "Documentation" : 15
    "Meetings" : 20
```
````

### Gantt Charts

Plan and track project timelines:

````markdown
```mermaid
gantt
    title Project Schedule
    dateFormat YYYY-MM-DD
    section Design
    Wireframes       :2024-01-01, 7d
    Mockups         :2024-01-08, 7d
    section Development
    Frontend        :2024-01-15, 14d
    Backend         :2024-01-15, 14d
    section Testing
    QA Testing      :2024-01-29, 7d
```
````

### Entity Relationship Diagrams

Model database relationships:

````markdown
```mermaid
erDiagram
    USER ||--o{ POST : creates
    USER {
        int id PK
        string email
        string name
    }
    POST {
        int id PK
        int userId FK
        string title
        text content
    }
    POST ||--o{ COMMENT : has
    COMMENT {
        int id PK
        int postId FK
        string content
    }
```
````

### Git Graphs

Visualize Git workflows:

````markdown
```mermaid
gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
```
````

## Configuration

### Default Settings

The Mermaid plugin uses these defaults:

* `startOnLoad: false` - Diagrams render on demand
* `theme: "default"` - Mermaid's default theme
* `securityLevel: "strict"` - Secure rendering
* `fontFamily: "monospace"` - Consistent code-like typography
* `suppressErrorRendering: true` - Prevents partial renders on errors

### Theme Customization

Customize the Mermaid theme using the `mermaid.config` prop:

```tsx title="chat.tsx" lineNumbers
import { Streamdown } from "streamdown";
import { mermaid } from "@streamdown/mermaid";
import type { MermaidConfig } from "@streamdown/mermaid";

export default function Page() {
  return (
    <Streamdown
      plugins={{ mermaid }}
      mermaid={{
        config: {
          theme: "dark",
          themeVariables: {
            primaryColor: "#ff6b6b",
            primaryTextColor: "#fff",
            primaryBorderColor: "#ff6b6b",
            lineColor: "#f5f5f5",
            secondaryColor: "#4ecdc4",
            tertiaryColor: "#45b7d1",
          },
        },
      }}
    >
      {markdown}
    </Streamdown>
  );
}
```

### Available Themes

Mermaid includes several built-in themes:

* `default` - Classic Mermaid theme
* `dark` - Dark mode optimized
* `forest` - Green tones
* `neutral` - Minimal styling
* `base` - Clean, modern style

Example:

```tsx
<Streamdown
  plugins={{ mermaid }}
  mermaid={{ config: { theme: "forest" } }}
>
  {markdown}
</Streamdown>
```

### Advanced Configuration

Customize specific diagram types:

```tsx
<Streamdown
  plugins={{ mermaid }}
  mermaid={{
    config: {
      theme: "base",
      themeVariables: {
        fontSize: "16px",
        fontFamily: "Inter, sans-serif",
      },
      flowchart: {
        nodeSpacing: 50,
        rankSpacing: 50,
        curve: "basis",
      },
      sequence: {
        actorMargin: 50,
        boxMargin: 10,
        boxTextMargin: 5,
      },
    },
  }}
>
  {markdown}
</Streamdown>
```

### Factory Function

For advanced configuration, use `createMermaidPlugin`:

```tsx
import { createMermaidPlugin } from '@streamdown/mermaid';

const mermaid = createMermaidPlugin({
  config: {
    theme: 'dark',
    fontFamily: 'monospace',
  },
});
```

## Error Handling

### Custom Error Component

When Mermaid diagrams fail to render due to invalid syntax, you can provide a custom error component. This is useful for production environments where you want to control the user experience.

```tsx title="chat.tsx" lineNumbers
import { Streamdown } from "streamdown";
import { mermaid } from "@streamdown/mermaid";
import type { MermaidErrorComponentProps } from "streamdown";

const CustomMermaidError = ({
  error,
  chart,
  retry,
}: MermaidErrorComponentProps) => (
  <div className="rounded-lg border border-amber-200 bg-amber-50 p-4">
    <div className="flex items-center gap-2">
      <span className="text-xl">⚠️</span>
      <p className="font-semibold text-amber-900">Couldn't render diagram</p>
    </div>
    <p className="mt-2 text-amber-700 text-sm">
      There was an issue with the diagram syntax.
    </p>
    <button
      onClick={retry}
      className="mt-3 rounded bg-amber-600 px-4 py-2 text-white text-sm hover:bg-amber-700"
    >
      Try Again
    </button>
  </div>
);

export default function Page() {
  return (
    <Streamdown
      plugins={{ mermaid }}
      mermaid={{
        errorComponent: CustomMermaidError,
      }}
    >
      {markdown}
    </Streamdown>
  );
}
```

The error component receives three props:

* **error** (`string`) - The error message from Mermaid
* **chart** (`string`) - The original Mermaid diagram code
* **retry** (`() => void`) - Function to retry rendering the diagram

### Example: Logging Errors

```tsx
const ErrorWithLogging = ({
  error,
  chart,
  retry,
}: MermaidErrorComponentProps) => {
  useEffect(() => {
    // Log to your error tracking service
    console.error("Mermaid rendering failed:", error);
    // Could also send to Sentry, LogRocket, etc.
  }, [error]);

  return (
    <div className="text-center p-4">
      <p className="text-muted-foreground">Unable to display diagram</p>
      <button onClick={retry} className="mt-2 text-primary text-sm underline">
        Retry
      </button>
    </div>
  );
};
```

## Interactive Controls

Each Mermaid diagram includes interactive controls:

### Fullscreen Mode

Click the fullscreen button to view the diagram in an overlay with a dark background. This is useful for complex diagrams.

### Download

Download the diagram as an SVG file for use in presentations or documentation.

### Copy

Copy the diagram to your clipboard for pasting into other applications.

### Customizing Controls

You can customize which controls are shown:

```tsx
<Streamdown
  plugins={{ mermaid }}
  controls={{
    mermaid: {
      fullscreen: true,
      download: true,
      copy: true,
      panZoom: true, // Enable pan and zoom controls
    },
  }}
>
  {markdown}
</Streamdown>
```

Or disable specific controls:

```tsx
<Streamdown
  plugins={{ mermaid }}
  controls={{
    mermaid: {
      fullscreen: true,
      download: false, // Hide download button
      copy: false, // Hide copy button
      panZoom: false, // Hide pan/zoom controls
    },
  }}
>
  {markdown}
</Streamdown>
```

Or disable all Mermaid controls:

```tsx
<Streamdown
  plugins={{ mermaid }}
  controls={{ mermaid: false }}
>
  {markdown}
</Streamdown>
```

## Streaming Considerations

### Initial Render

When Mermaid diagrams are first streamed in, they appear as code blocks until the diagram syntax is complete. Streamdown's parser ensures the code block is properly formatted during streaming.

### Avoid Continuous Re-rendering

Mermaid diagrams are expensive to render. During streaming, you don't want to re-render the diagram on every chunk — that would be slow and cause flickering. Use the `useIsCodeFenceIncomplete` hook to wait until the code block is complete before rendering:

```tsx
import { Streamdown, useIsCodeFenceIncomplete } from "streamdown";
import { mermaid } from "@streamdown/mermaid";

const MyMermaidBlock = ({ children }) => {
  const isIncomplete = useIsCodeFenceIncomplete();

  if (isIncomplete) {
    return (
      <div className="animate-pulse bg-muted h-48 rounded-lg flex items-center justify-center">
        <span className="text-muted-foreground">Loading diagram...</span>
      </div>
    );
  }

  // Only render Mermaid once the code block is fully received
  return <Mermaid chart={children} />;
};
```

This shows a placeholder while the code block is streaming, then renders the Mermaid diagram only once the closing ` ``` ` is received — without waiting for the entire markdown stream to finish.

### Disable Interactions During Streaming

Use the `isAnimating` prop to disable interactive controls while content is streaming:

```tsx
<Streamdown
  plugins={{ mermaid }}
  isAnimating={isStreaming}
>
  {markdown}
</Streamdown>
```

This prevents users from interacting with incomplete diagrams.

## Syntax Reference

### Flowchart Links

```
A --> B         // Arrow
A --- B         // Line
A -.-> B        // Dotted arrow
A ==> B         // Thick arrow
A -->|Label| B  // Labeled arrow
```

### Sequence Diagram Actors

```
participant A as Alice
actor B as Bob
```

### Styling Nodes

<Mermaid
  chart="graph TD
    A[Node]
    style A fill:#f9f,stroke:#333,stroke-width:4px"
/>

### Subgraphs

<Mermaid
  chart="graph TD
    subgraph Group A
        A1 --> A2
    end
    subgraph Group B
        B1 --> B2
    end
    A2 --> B1"
/>

## Best Practices

### Keep Diagrams Focused

Break complex diagrams into smaller, focused visualizations:

````markdown
✅ Good: Multiple small diagrams

## User Authentication Flow

```mermaid
graph LR
    A[Login] --> B{Valid?}
    B -->|Yes| C[Dashboard]
    B -->|No| D[Error]
```

## Data Fetching Flow

```mermaid
graph LR
    A[Request] --> B[API]
    B --> C[Database]
    C --> B
    B --> D[Response]
```

❌ Avoid: One massive diagram with everything
````

### Add Context

Provide descriptions for your diagrams:

````markdown
Here's the authentication flow for our application:

```mermaid
sequenceDiagram
    User->>App: Enter credentials
    App->>Server: Authenticate
    Server-->>App: Token
    App-->>User: Success
```

The server validates credentials and returns a JWT token.
````

### Use Descriptive Labels

Make your diagrams self-documenting:

````markdown
✅ Good: Clear labels

```mermaid
graph TD
    A[User clicks 'Submit'] --> B{Form valid?}
    B -->|Yes| C[Send to server]
    B -->|No| D[Show validation errors]
```

❌ Avoid: Cryptic labels

```mermaid
graph TD
    A[Step 1] --> B{Check}
    B -->|OK| C[Next]
    B -->|Bad| D[Err]
```
````

### Choose the Right Diagram Type

Select the diagram type that best represents your information:

* **Flowchart** - Processes, algorithms, workflows
* **Sequence** - API interactions, communication flows
* **State** - Lifecycle, state machines
* **Class** - Object relationships, architecture
* **ER** - Database schemas
* **Gantt** - Project timelines
* **Pie/Bar** - Statistical data

## Common Issues

### Diagram Not Rendering

1. Verify the Mermaid plugin is passed to Streamdown
2. Verify the syntax is correct (check [Mermaid Live Editor](https://mermaid.live/))
3. Ensure the code block uses ` ```mermaid `
4. Check browser console for JavaScript errors

### Performance with Large Diagrams

Large diagrams may take time to render. Consider:

* Breaking into smaller diagrams
* Simplifying node relationships
* Using subgraphs for organization
* Lazy loading diagram-heavy pages

### Theme Not Applying

1. Verify `mermaid.config` is properly passed
2. Check that theme name is spelled correctly
3. Ensure custom theme variables are valid

## Plugin Interface

The Mermaid plugin implements the `DiagramPlugin` interface:

```tsx
interface DiagramPlugin {
  name: "mermaid";
  type: "diagram";
  language: string; // "mermaid"
  getMermaid: (config?: MermaidConfig) => MermaidInstance;
}
```

The `language` property indicates which code block language triggers diagram rendering.

## Resources

* [Mermaid Documentation](https://mermaid.js.org/intro/) - Official docs
* [Mermaid Live Editor](https://mermaid.live/) - Test diagrams online
* [Syntax Reference](https://mermaid.js.org/intro/syntax-reference.html) - Complete syntax guide
* [Mermaid Examples](https://mermaid.js.org/ecosystem/integrations.html) - Gallery of examples

## Related Features

* [Code Blocks](/docs/code-blocks) - Syntax highlighting for other code
* [GitHub Flavored Markdown](/docs/gfm) - Extended Markdown features
* [Typography](/docs/typography) - Text styling around diagrams
* [Unterminated Block Parsing](/docs/termination) - How streaming works with Mermaid


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)