Configuration

The plugin accepts a configuration object when registered with markdown-it.
These options control which icon collections are available and how icons are rendered.

Type Definitions

import { IconifyJSON, IconifyIcon } from "@iconify/types";

/**
 * Represents the raw data of an icon.
 */
export type IconData = {
  /**
   * The SVG content of the icon. Must already be sanitized to prevent XSS when injected into HTML.
   */
  body: string
  /**
   * Optional attributes to apply to the root SVG element.
   */
  attributes?: Record<string, string>
}

/**
 * A function to resolve an icon dynamically.
 * @param collection name of the collection requested
 * @param name icon name within the collection
 * @return `undefined` if the icon cannot be found.
 */
export type IconResolver = (
    collection: string | undefined,
    name: string,
) => IconifyIcon | IconData | undefined

/**
 * @param collection name of the collection requested
 * @param name icon name within the collection
 * @param attributes html-attributes to add to the svg-html
 * @return svg-html or undefined if not found
 */
export type IconRenderer = (
    collection: string | undefined,
    name: string,
    attributes?: Record<string, string>,
) => string | undefined

/**
 * Options passed to `createIconRenderer`.
 */
export interface CreateIconRendererOptions {
  /**
   * Map of collection name -> Iconify icon set.
   * Example: { lucide, "simple-icons": simpleIcons }
   */
  collections: Record<string, IconifyJSON>

  /**
   * Optional default collection name.
   * If provided, icons without a collection prefix use this collection.
   * If omitted, unprefixed icons are ignored.
   */
  defaultCollection?: string | IconifyJSON

  /**
   * Optional resolver for non-Iconify icons or dynamic icons.
   * Useful for fetching icons from external sources or custom collections.
   */
  iconResolver?: IconResolver

  /**
   * Default height for rendered icons.
   * Width will scale automatically to maintain aspect ratio.
   */
  height?: string

  /**
   * CSS class to apply to every rendered icon element.
   */
  iconClass?: string
}

Example Configuration

import MarkdownIt from "markdown-it";
import iconPlugin from "mdit-plugin-iconify";
import { icons as lucide } from "@iconify-json/lucide";
import { icons as social } from "@iconify-json/simple-icons";

const md = new MarkdownIt();

md.use(iconPlugin, {
  collections: {
    lucide,
    social,
  },
  defaultCollection: "lucide",
  iconClass: "iconify",
  height: "1.2em",
});

This configuration enables both Lucide and Simple Icons, sets "lucide" as the default collection, and applies the custom .iconify class to all icons.

Advanced Use: Custom Resolver

You can provide an iconResolver to fetch icons dynamically from an API, filesystem, or custom source.

async iconResolver are currently unsupported

md.use(iconPlugin, {
  collections: { lucide },
  iconResolver: async (collection, name) => {
    if (collection === "remote") {
      const res = await fetch(`https://example.com/icons/${name}.svg`);
      const svg = await res.text();
      return { body: svg };
    }
  },
});

This approach lets you extend the plugin beyond Iconify JSON sets while keeping the same syntax.