Icon support

​

Overview

• Register icon packs from the Iconify ecosystem
• Load icons from CDN or bundled packages
• Use custom names for icon packs (overriding the default prefix)
• Lazy load icon packs only when used in diagrams

​

Registering icon packs

​

Using CDN

import mermaid from 'mermaid';

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

​

Using packages with lazy loading

npm install @iconify-json/logos@1

import mermaid from 'mermaid';

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

​

Using packages without lazy loading

npm install @iconify-json/logos@1

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

mermaid.registerIconPacks([
  {
    name: icons.prefix,  // Use the default prefix from the pack
    icons,
  },
]);

​

Icon pack configuration

​

Custom names vs. default prefix

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

// Use as: brands:icon-name

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

mermaid.registerIconPacks([
  {
    name: icons.prefix,  // Use default prefix (e.g., 'logos')
    icons,
  },
]);

// Use as: logos:icon-name

​

Using icons in diagrams

​

Flowchart example

​

Architecture diagram example

​

Available icon packs

​

Brand icons

• @iconify-json/logos - Brand and technology logos
• @iconify-json/simple-icons - Simple icons for popular brands
• @iconify-json/devicon - Programming languages and development tools

​

General purpose

• @iconify-json/fa6-solid - Font Awesome 6 Solid
• @iconify-json/fa6-regular - Font Awesome 6 Regular
• @iconify-json/mdi - Material Design Icons
• @iconify-json/heroicons - Heroicons

​

Specialized

• @iconify-json/emojione - Emoji One
• @iconify-json/twemoji - Twitter Emoji
• @iconify-json/noto - Google Noto Emoji

​

Best practices

​

Performance optimization

• Use lazy loading - Load icon packs only when needed
• Register specific packs - Don’t register icon packs you won’t use
• Bundle icons in production - For better performance, bundle frequently used icons

​

Naming conventions

• Use short custom names - Make icon references easier to type
• Be consistent - Use the same naming pattern across your application
• Document your icons - Keep a list of registered icon packs

​

Error handling

mermaid.registerIconPacks([
  {
    name: 'logos',
    loader: async () => {
      try {
        const res = await fetch('https://unpkg.com/@iconify-json/logos@1/icons.json');
        if (!res.ok) {
          throw new Error(`Failed to load icons: ${res.status}`);
        }
        return await res.json();
      } catch (error) {
        console.error('Icon pack loading failed:', error);
        // Return empty icon set or fallback
        return { icons: {} };
      }
    },
  },
]);

​

Complete example

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

mermaid.initialize({
  startOnLoad: true,
  theme: 'default',
});

mermaid.registerIconPacks([
  // Bundled logos (no lazy loading)
  {
    name: 'logos',
    icons: logos,
  },
  // Lazy loaded Font Awesome
  {
    name: 'fa',
    loader: () => import('@iconify-json/fa6-solid')
      .then((module) => module.icons),
  },
  // CDN loaded Material Design Icons
  {
    name: 'mdi',
    loader: () =>
      fetch('https://unpkg.com/@iconify-json/mdi@1/icons.json')
        .then((res) => res.json()),
  },
]);

​

Troubleshooting

​

Icons not displaying

1. Check pack registration - Ensure the icon pack is registered before rendering diagrams
2. Verify icon name - Check that the icon exists in the pack at icones.js.org
3. Check syntax - Use packName:iconName format
4. Inspect console - Look for loading errors in browser console

​

Performance issues

• Use lazy loading - Don’t load all icons upfront
• Minimize pack size - Only register packs you actually use
• Cache CDN responses - Configure proper cache headers

​

Next steps