@ai-matrx/icons

Turn any icon name into a rendered component. One resolver, four sources, zero flash-of-nothing:

• A curated static map of ~140 hot Lucide icons — a hit renders synchronously, no dynamic-import latency. The map is exported (staticLucideIconMap) and extensible (extendStaticIcons).
• The full Lucide catalog via a validated dynamic import("lucide-react") — resolved once, cached at module level, with the export checked to actually be a renderable component before it is ever rendered.
• Curated brand icons from the react-icons optional dependency — installed by default, lazy-imported on first use; when react-icons is absent (install with --omit=optional, or a failed optional install) the resolver degrades to the fallback icon instead of failing. lucide-react itself is a real dependency — the package carries its own catalog; react is the only peer.
• Your own SVG assets via svg: ids — an injectable registry maps svg:icons/Home → /icons/Home.svg and renders an <img>; you register your app's asset paths once at startup.

While a dynamic icon loads, the fallback icon (default Zap) renders in its place — the layout never jumps and nothing flashes empty.

npm install @ai-matrx/icons lucide-react
# optional, for the curated brand icons (FcGoogle, FaBrave, …):
npm install react-icons

Peers: react >= 18, lucide-react >= 0.400.0, and optionally react-icons >= 5.

Usage

import { IconResolver, DynamicIcon, getIconComponent, renderIcon } from "@ai-matrx/icons";

// The unified component — static, dynamic, custom, and svg: names all work:
<IconResolver iconName="AlarmClock" className="h-4 w-4" />

// Color/size convenience wrapper (Tailwind color names or hex):
<DynamicIcon name="Home" color="blue" size={5} />
<DynamicIcon name="Home" color="#ff6600" size={5} />

// Synchronous lookup (static map + already-cached icons only; always returns a component):
const Icon = getIconComponent("Settings");

// Direct element render:
{renderIcon("Check", { className: "h-4 w-4" })}

Existence checks (never infer existence from getIconComponent, which always returns a component): isIconRegisteredSync(name) for the synchronous registries, await isRegisteredOrLucideIconName(name) for the full check including the Lucide catalog.

Name normalization for user-typed/pasted input: collectLucideIconNameCandidates("alarm-clock") → ["alarm-clock", "Alarm-clock", "AlarmClock"], and extractLucideJsxIconName("<BugPlay />") → "BugPlay" — validate candidates with isRegisteredOrLucideIconName.

Icon pickers: getCuratedIconIdsForPicker() returns the finite, sorted set of every static Lucide name, curated brand id, and registered svg: id.

Registering your app's SVG assets

The package ships with an empty svg: registry — register your public asset paths once at startup (any module that runs before icons render):

import { registerSvgIcons } from "@ai-matrx/icons";

registerSvgIcons({
  "icons/Home": "/icons/Home.svg",
  "icons/brands/microsoft": "/icons/brands/microsoft.svg",
  "icons/copy": "/icons/copy.svg",
  "icons/hamburger": "/icons/hamburger.svg",
  "icons/loading-circle": "/icons/loading-circle.svg",
  "icons/logo": "/icons/logo.svg",
  "icons/play": "/icons/play.svg",
  "icons/share": "/icons/share.svg",
  "icons/three-dots": "/icons/three-dots.svg",
  "matrx/matrx-icon": "/matrx/matrx-icon.svg",
  "matrx/matrx-icon-blue": "/matrx/matrx-icon-blue.svg",
  "matrx/matrx-icon-cyan": "/matrx/matrx-icon-cyan.svg",
  "matrx/matrx-icon-green": "/matrx/matrx-icon-green.svg",
  "matrx/matrx-icon-indigo": "/matrx/matrx-icon-indigo.svg",
  "matrx/matrx-icon-orange": "/matrx/matrx-icon-orange.svg",
  "matrx/matrx-icon-pink": "/matrx/matrx-icon-pink.svg",
  "matrx/matrx-icon-purple": "/matrx/matrx-icon-purple.svg",
  "matrx/matrx-icon-slate": "/matrx/matrx-icon-slate.svg",
  "matrx/matrx-icon-teal": "/matrx/matrx-icon-teal.svg",
  "matrx/matrx-icon-yellow": "/matrx/matrx-icon-yellow.svg",
  "matrx/matrx-imagen-logo-text": "/matrx/matrx-imagen-logo-text.svg",
  "matrx/safari-pinned-tab": "/matrx/safari-pinned-tab.svg",
  "dark-turbulence-noise": "/dark-turbulence-noise.svg",
});

Then <IconResolver iconName="svg:matrx/matrx-icon" size={24} /> renders <img src="/matrx/matrx-icon.svg" …>. Calls merge, so features can register their own ids independently. An unregistered svg: id falls back like any unknown name.

Keeping your own hot icons synchronous

import { BrainCircuit } from "lucide-react";
import { extendStaticIcons } from "@ai-matrx/icons";

extendStaticIcons({ BrainCircuit }); // now a zero-latency static hit everywhere

Design

• The static map + validated dynamic import + module cache + fallback-while-loading architecture is the product; the curated hot set ships in the package.
• react-icons is optional by construction: it is only ever loaded lazily, and every path degrades to the fallback icon when it is absent.
• Class names in helpers (getTextColorClass, DynamicIcon sizing) are Tailwind-shaped strings; the package ships no CSS.
• ESM + CommonJS conditions with matching declarations, proven from the packed tarball, "use client" stamped on every built chunk.

MIT © AI Matrx