How to Configure Font Rendering in Mermaid Using fontFamily and altFontFamily

You can control Mermaid diagram typography by setting the fontFamily and altFontFamily configuration properties, which the rendering engine applies to SVG text elements and canvas contexts to define primary font stacks and glyph fallbacks.

The mermaid-js/mermaid library uses browser-native text rendering to display labels in flowcharts, sequence diagrams, and other visualizations. By default, it relies on generic sans-serif system fonts, but you can override this behavior globally or per-diagram using the fontFamily and altFontFamily options defined in the core configuration system.

Understanding fontFamily and altFontFamily

Mermaid accepts two distinct font-related settings at the top level of its configuration object. These values are stored in the global config instance during initialization and referenced throughout the rendering lifecycle.

What fontFamily Controls

The fontFamily property defines the primary font stack for all diagram text. It accepts any valid CSS font-family value, including multiple font names separated by commas. This string is injected directly into SVG <text> style attributes and canvas font contexts. According to the source code in src/diagrams/common/config.js, user-provided values merge with internal defaults during mermaid.initialize().

What altFontFamily Controls

The altFontFamily property serves as the ultimate fallback when the primary font lacks specific glyphs. This prevents missing-character boxes when rendering international text or special symbols. The browser automatically steps through the font stack: first fontFamily, then altFontFamily, and finally generic system defaults.

How Mermaid Applies Font Configuration

The rendering pipeline applies font settings in three distinct phases, ensuring consistent typography across SVG and canvas outputs.

Configuration Initialization

When you call mermaid.initialize(), the library merges your configuration object with defaults stored in src/diagrams/common/configDefaults.js. The merging logic in src/diagrams/common/config.js stores the final fontFamily and altFontFamily values on the global configuration instance. This occurs before any diagram parsing begins, meaning font settings affect all diagram types—including flowcharts, sequence diagrams, and Gantt charts—without requiring per-diagram tweaks.

SVG and Canvas Rendering Pipeline

During diagram generation, Mermaid constructs the final font string by combining both properties:

1. SVG Rendering: In src/diagrams/common/renderer/svgRenderer.js, the engine sets the style attribute of <text> nodes to font-family: <fontFamily>, <altFontFamily>.
2. Canvas Rendering: In src/diagrams/common/renderer/canvasRenderer.js, the concatenated font string is assigned to the canvas context via ctx.font.
3. Glyph Fallback: If a character is missing from the primary font, the browser automatically selects the next available font in the stack, eventually falling back to the generic family specified in altFontFamily.

Practical Configuration Examples

You can configure fonts globally for an entire page or locally for individual diagrams using the %%init%% directive.

Global Configuration with mermaid.initialize

Set default fonts for all diagrams on the page by passing options to the initialization method:

mermaid.initialize({
  startOnLoad: true,
  theme: 'default',
  fontFamily: 'Helvetica, Arial, sans-serif',
  altFontFamily: 'sans-serif',
});

Per-Diagram Configuration with init Directive

Override global settings for a single diagram using the init directive at the start of your Mermaid code block:

```mermaid
%%{init: {'fontFamily':'"Courier New", monospace', 'altFontFamily':'monospace'} }%%
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Result A]
    B -->|No| D[Result B]

You can also use this syntax when calling `mermaid.render()` programmatically:

```javascript
mermaid.render('id1', `
  %%{init: {'fontFamily':'"Times New Roman", serif', 'altFontFamily':'serif'} }%%
  sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Hello Bob, how are you?
    Bob-->>Alice: I am good!
`);

Loading Custom Web Fonts

To use external fonts like Google Fonts, ensure the font loads via CSS or <link> tags before Mermaid renders the diagram:

<link href="https://fonts.googleapis.com/css2?family=Roboto+Mono&display=swap" rel="stylesheet">
<script>
  mermaid.initialize({
    fontFamily: '"Roboto Mono", monospace',
    altFontFamily: 'monospace',
  });
</script>

Summary

• The fontFamily option sets the primary CSS font stack for all diagram text, while altFontFamily provides the final fallback for missing glyphs.
• Configuration merging occurs in src/diagrams/common/config.js, with defaults defined in src/diagrams/common/configDefaults.js.
• The rendering pipeline in src/diagrams/common/renderer/svgRenderer.js and src/diagrams/common/renderer/canvasRenderer.js applies these fonts to SVG elements and canvas contexts respectively.
• You can configure fonts globally via mermaid.initialize() or per-diagram using the %%{init: {}}%% directive.
• Both settings accept standard CSS font-family values, including multi-font stacks and web fonts.

Frequently Asked Questions

What is the difference between fontFamily and altFontFamily in Mermaid?

The fontFamily option defines the primary font stack used for all text rendering, equivalent to the CSS font-family property. The altFontFamily acts as a final fallback when the primary fonts lack specific glyphs, ensuring characters render correctly across different languages and symbol sets.

How do I use a custom Google Font with Mermaid?

First load the font via a <link> tag or @import CSS rule to ensure it is available in the browser. Then set fontFamily to the custom font name followed by a fallback generic family (e.g., "Roboto Mono", monospace). Mermaid will reference this stack during SVG and canvas rendering.

Can I configure fonts for a single diagram without affecting others?

Yes. Use the %%{init: {}}%% directive at the beginning of your Mermaid diagram definition to override global settings for that specific diagram only. This is useful when you need different typography for individual charts within the same documentation page.

Where are the default font values defined in the Mermaid source code?

Default configuration values reside in src/diagrams/common/configDefaults.js. The merging logic that combines user settings with these defaults is implemented in src/diagrams/common/config.js, which initializes the global configuration instance used by the rendering engines.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}