@versini/ui-icon-renderer

A React hook for lazy-loading icons from @versini/ui-icons on demand.

The Icon Renderer package provides useIconRenderer, a hook that dynamically imports icons by name at runtime. This avoids bundling all 100+ icons upfront, making it ideal for components like icon pickers where the full icon set is needed but shouldn't impact initial bundle size.

Table of Contents

• Features
• Installation
• Usage
• API

Features

• 🚀 Lazy Loading: Icons are loaded on demand via dynamic imports — no upfront bundle cost
• ⚡ Optional Preloading: Warm the cache ahead of time to prevent flash on render
• 🧩 Simple Hook API: Single useIconRenderer hook covers all use cases
• 🌲 Tree-shakeable: Only the hook is included in your bundle, icon data stays lazy
• 🔧 TypeScript: Fully typed with comprehensive prop definitions
• 📦 Shared Cache: Module-level cache ensures each icon is loaded only once across components

Installation

npm install @versini/ui-icon-renderer

Note: This package requires @versini/ui-icons as a peer dependency.

Usage

Render Icons Without Preloading

When you don't know which icon will be needed ahead of time, or preloading isn't necessary. The icon loads automatically when rendered (brief null while loading).

import { useIconRenderer } from "@versini/ui-icon-renderer";

function App() {
  const [IconRenderer] = useIconRenderer();
  const [selectedIcon, setSelectedIcon] = useState<string | null>(null);

  return (
    <div>
      <button onClick={() => setSelectedIcon("IconAdd")}>Show Icon</button>
      {selectedIcon && IconRenderer && <IconRenderer icon={selectedIcon} />}
    </div>
  );
}

Preload Icons to Prevent Flash

When you know which icons will be needed, preload them before rendering to avoid a flash of empty content.

import { useIconRenderer } from "@versini/ui-icon-renderer";

function App() {
  const [IconRenderer, preloadIcons] = useIconRenderer();
  const [showIcons, setShowIcons] = useState(false);

  return (
    <div>
      <button
        onMouseEnter={() => preloadIcons(["IconAdd", "IconDelete", "IconEdit"])}
        onClick={() => setShowIcons(true)}
      >
        Show Icons
      </button>
      {showIcons && IconRenderer && (
        <div>
          <IconRenderer icon="IconAdd" />
          <IconRenderer icon="IconDelete" />
          <IconRenderer icon="IconEdit" />
        </div>
      )}
    </div>
  );
}

Icon Picker

Load all available icons lazily for an icon picker component.

import { useIconRenderer } from "@versini/ui-icon-renderer";

const ALL_ICON_NAMES = ["IconAdd", "IconDelete", "IconEdit", "IconSearch"];

function IconPicker({ onSelect }: { onSelect: (name: string) => void }) {
  const [IconRenderer, preloadIcons] = useIconRenderer();

  useEffect(() => {
    preloadIcons(ALL_ICON_NAMES);
  }, [preloadIcons]);

  if (!IconRenderer) {
    return null;
  }

  return (
    <div className="grid grid-cols-6 gap-2">
      {ALL_ICON_NAMES.map((name) => (
        <button key={name} onClick={() => onSelect(name)}>
          <IconRenderer icon={name} />
        </button>
      ))}
    </div>
  );
}

API

useIconRenderer

const [IconRenderer, preloadIcons] = useIconRenderer();

Returns a tuple:

| Index | Name | Type | Description | | ----- | ------------ | ------------------------------------- | ---------------------------------------------------------------------------------------------- | | 0 | IconRenderer | React.FC<IconRendererProps> \| null | The icon component, or null while the module is loading. Available after first render cycle. | | 1 | preloadIcons | (icons: string[]) => Promise<void> | Preloads icon data into the cache. Optional — icons auto-load when rendered if not preloaded. |

IconRenderer Props

| Prop | Type | Default | Description | | --------- | -------- | ------- | ---------------------------------------------------------------------- | | icon | string | - | The name of the icon to render (e.g. "IconAdd", "IconDeleteLight") | | className | string | - | CSS class(es) to add to the SVG element |

Also accepts all standard SVG element props (React.ComponentPropsWithoutRef<"svg">).