mermaid/docs/config/icons.md

Warning

THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.

Please edit the corresponding file in /packages/mermaid/src/docs/config/icons.md.

Icon Pack Configuration

Mermaid supports icons through Iconify-compatible icon packs. You can register icon packs either declaratively via configuration (recommended for most use cases) or programmatically via JavaScript API (for advanced/offline scenarios).

Declarative Configuration (v<MERMAID_RELEASE_VERSION>+) (Recommended)

The easiest way to use icons in Mermaid is through declarative configuration. This works in browsers, CLI, Live Editor, and headless renders without requiring custom JavaScript.

Basic Usage

Configure icon packs in your Mermaid config:

---
config:
  icons:
    packs:
      logos: "@iconify-json/logos@1"
---
flowchart TB
  A[Start] --> B@{ icon: 'logos:docker', label: 'Docker' }
  B --> C[End]

Or in JavaScript:

mermaid.initialize({
  icons: {
    packs: {
      logos: '@iconify-json/logos@1',
      'simple-icons': '@iconify-json/simple-icons@1',
    },
  },
});

Package Spec Format

Icon packs are specified using package specs with version pinning:

• Format: @scope/package@<version> or package@<version>
• Must include at least a major version (e.g., @iconify-json/logos@1)
• Minor and patch versions are optional (e.g., @iconify-json/logos@1.2.3)

Important: Only package specs are supported. Direct URLs are not allowed for security reasons.

Configuration Options

icons:
  packs:
    # Icon pack configuration
    # Key: local name to use in diagrams
    # Value: package spec with version
    logos: '@iconify-json/logos@1'
    'simple-icons': '@iconify-json/simple-icons@1'

  # CDN template for resolving package specs
  # Must contain ${packageSpec} placeholder
  cdnTemplate: 'https://cdn.jsdelivr.net/npm/${packageSpec}/icons.json'

  # Maximum file size in MB for icon pack JSON files
  # Range: 1-10 MB, default: 5 MB
  maxFileSizeMB: 5

  # Network timeout in milliseconds for icon pack fetches
  # Range: 1000-30000 ms, default: 5000 ms
  timeout: 5000

  # List of allowed hosts to fetch icons from
  allowedHosts:
    - 'unpkg.com'
    - 'cdn.jsdelivr.net'
    - 'npmjs.com'

Security Features

• Host allowlisting: Only fetch from hosts in allowedHosts
• Size limits: Maximum file size enforced via maxFileSizeMB
• Timeouts: Network requests timeout after specified milliseconds
• HTTPS only: All remote fetches occur over HTTPS
• Version pinning: Package specs must include version for reproducibility

Examples

Using Custom CDN Template

---
config:
  icons:
    packs:
      logos: "@iconify-json/logos@1"
    cdnTemplate: "https://unpkg.com/${packageSpec}/icons.json"
---
flowchart TB
  A[Start] --> B@{ icon: 'logos:aws', label: 'AWS' }

Multiple Icon Packs

---
config:
  icons:
    packs:
      logos: "@iconify-json/logos@1"
      "simple-icons": "@iconify-json/simple-icons@1"
---
flowchart TB
  A@{ icon: 'logos:docker', label: 'Docker' } --> B@{ icon: 'simple-icons:github', label: 'GitHub' }

CLI Usage

Create a mermaid.json config file:

{
  "icons": {
    "packs": {
      "logos": "@iconify-json/logos@1"
    }
  }
}

Then use it with the CLI:

mmdc -i diagram.mmd -o diagram.svg --configFile mermaid.json

Programmatic API (v11.1.0+) (Advanced)

For advanced scenarios or offline use, you can register icon packs programmatically:

Using JSON File from CDN

import mermaid from 'CDN/mermaid.esm.mjs';

mermaid.registerIconPacks([
  {
    name: 'logos',
    loader: () =>
      fetch('https://unpkg.com/@iconify-json/logos@1/icons.json').then((res) => res.json()),
  },
]);

Using Packages with Bundler

Install the icon pack:

npm install @iconify-json/logos@1

With Lazy Loading

import mermaid from 'mermaid';

mermaid.registerIconPacks([
  {
    name: 'logos',
    loader: () => import('@iconify-json/logos').then((module) => module.icons),
  },
]);

Without Lazy Loading

import mermaid from 'mermaid';
import { icons } from '@iconify-json/logos';

mermaid.registerIconPacks([
  {
    name: icons.prefix, // Use the prefix defined in the icon pack
    icons,
  },
]);

Finding Icon Packs

Icon packs available for use can be found at iconify.design or icones.js.org.

The pack name you register is the local name used in diagrams. It can differ from the pack's prefix, allowing you to:

• Use shorter names (e.g., register @iconify-json/material-design-icons as mdi)
• Load specific packs only when used in diagrams (lazy loading)

Error Handling

If an icon cannot be found:

• The diagram still renders (non-fatal)
• A fallback icon is displayed
• A warning is logged (visible in CLI stderr or browser console)

Licensing

Iconify JSON format is MIT licensed, but individual icons may have varying licenses. Please verify the licenses of the icon packs you configure before use in production.

Mermaid does not redistribute third-party icon assets in the core bundle.