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.

Properties

Option	Type	Required	Default	Description
collections	Record<string, IconifyIcons>		–	Defines available icon sets. Each key is a collection name mapped to its Iconify JSON data.
defaultCollection	string		–	Sets a fallback collection. Icons without an explicit collection-name use this.
iconClass	string		"icon"	Base CSS class applied to every rendered icon.
height	string		"1em"	Default icon height; width scales automatically.
iconResolver	(collection: string, name: string) => IconData | Promise<IconData> | undefined		–	Custom resolver for loading icons dynamically or from non-Iconify sources.

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.
 * Can return either synchronously or asynchronously. (asynchronously currently unsupported)
 * Return `undefined` if the icon cannot be found.
 */
export type IconResolver = (
    /** The name of the collection requested */
    collection: string,
    /** The icon name within the collection */
    name: string,
) => IconifyIcon | undefined | Promise<IconifyIcon | undefined>

/**
 * Options that control the rendering of individual icons.
 */
export interface IconRenderOptions {
  /**
   * 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
}

/**
 * Options passed to `mdit-plugin-iconify`.
 */
export interface IconifyPluginOptions extends IconRenderOptions {
  /**
   * 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

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

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 .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.