# How to Configure Font Rendering in Mermaid Using fontFamily and altFontFamily

> Customize Mermaid diagram fonts with fontFamily and altFontFamily. Control SVG text and canvas rendering for primary font stacks and glyph fallbacks. Learn how to optimize your typography.

- Repository: [mermaid-js/mermaid](https://github.com/mermaid-js/mermaid)
- Tags: configuration
- Published: 2026-02-23

---

**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`](https://github.com/mermaid-js/mermaid/blob/main/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`](https://github.com/mermaid-js/mermaid/blob/main/src/diagrams/common/configDefaults.js). The merging logic in [`src/diagrams/common/config.js`](https://github.com/mermaid-js/mermaid/blob/main/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`](https://github.com/mermaid-js/mermaid/blob/main/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`](https://github.com/mermaid-js/mermaid/blob/main/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:

```javascript
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:

```markdown

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

```html
<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`](https://github.com/mermaid-js/mermaid/blob/main/src/diagrams/common/config.js), with defaults defined in [`src/diagrams/common/configDefaults.js`](https://github.com/mermaid-js/mermaid/blob/main/src/diagrams/common/configDefaults.js).
- The rendering pipeline in [`src/diagrams/common/renderer/svgRenderer.js`](https://github.com/mermaid-js/mermaid/blob/main/src/diagrams/common/renderer/svgRenderer.js) and [`src/diagrams/common/renderer/canvasRenderer.js`](https://github.com/mermaid-js/mermaid/blob/main/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`](https://github.com/mermaid-js/mermaid/blob/main/src/diagrams/common/configDefaults.js). The merging logic that combines user settings with these defaults is implemented in [`src/diagrams/common/config.js`](https://github.com/mermaid-js/mermaid/blob/main/src/diagrams/common/config.js), which initializes the global configuration instance used by the rendering engines.