or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

api-loading.mdbuilding.mdcomponents.mdindex.mdoffline.mdstorage.md
tile.json

tessl/npm-iconify--react

React component for rendering SVG icons from the Iconify ecosystem with over 200,000 icons from 150+ icon sets.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@iconify/react@6.0.x

To install, run

npx @tessl/cli install tessl/npm-iconify--react@6.0.0

index.mddocs/

Iconify for React

Iconify for React is a React icon component library that provides access to over 200,000 icons from 150+ icon sets through the Iconify ecosystem. Unlike traditional icon libraries that bundle all icons, this component loads icon data on demand from the Iconify API, resulting in smaller bundle sizes and better performance. The component supports extensive customization options and renders pixel-perfect SVG icons.

Package Information

  • Package Name: @iconify/react
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @iconify/react

Core Imports

ESM (default):

import { Icon, InlineIcon, loadIcons, addIcon } from "@iconify/react";

For offline usage:

import { Icon, InlineIcon, addIcon, addCollection } from "@iconify/react/offline";

CommonJS:

const { Icon, InlineIcon, loadIcons, addIcon } = require("@iconify/react");

Basic Usage

Online Mode (API-based)

import { Icon, InlineIcon } from "@iconify/react";

function App() {
  return (
    <div>
      {/* Block icon - centers vertically */}
      <Icon icon="mdi:home" />
      
      {/* Inline icon - aligns with text baseline */}
      <InlineIcon icon="mdi:account" />
      
      {/* With customizations */}
      <Icon 
        icon="mdi:heart" 
        color="red" 
        width="32" 
        height="32" 
        rotate={1} 
      />
      
      {/* With fallback content */}
      <Icon 
        icon="missing:icon" 
        fallback={<span>Loading...</span>}
      />
    </div>
  );
}

Offline Mode

import { Icon, addIcon, addCollection } from "@iconify/react/offline";

// Add individual icon
addIcon("custom-icon", {
  body: '<path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/>',
  width: 24,
  height: 24
});

// Add icon collection
addCollection({
  prefix: "custom",
  icons: {
    star: {
      body: '<path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/>',
    }
  },
  width: 24,
  height: 24
});

function OfflineApp() {
  return (
    <div>
      <Icon icon="custom-icon" />
      <Icon icon="custom:star" />
    </div>
  );
}

Architecture

Iconify for React is built around several key components:

  • React Components: Icon and InlineIcon components for different display modes
  • Storage System: Icon data storage and retrieval with automatic loading from API
  • API Integration: Automatic loading of icon data from Iconify API on demand
  • Offline Support: Pre-loaded icon usage without API calls via /offline sub-package
  • Customization Engine: Extensive icon transformation and styling options
  • Type Safety: Full TypeScript support with comprehensive type definitions

Capabilities

React Components

Core React components for rendering icons with different display behaviors and extensive customization options.

const Icon: React.ForwardRefExoticComponent<IconProps & React.RefAttributes<IconElement>>;
const InlineIcon: React.ForwardRefExoticComponent<IconProps & React.RefAttributes<IconElement>>;

interface IconProps extends React.SVGProps<SVGSVGElement>, IconifyIconProps {}

interface IconifyIconProps extends IconifyIconCustomisations {
  icon: IconifyIcon | string;
  mode?: IconifyRenderMode;
  color?: string;
  flip?: string;
  id?: string;
  ssr?: boolean;
  fallback?: React.ReactNode;
  onLoad?: IconifyIconOnLoad;
}

React Components

Icon Storage Management

Functions for managing icon data in local storage, including loading, checking, and adding icons.

function iconLoaded(name: string): boolean;
function getIcon(name: string): IconifyIcon | null;
function listIcons(provider?: string, prefix?: string): string[];
function addIcon(name: string, data: IconifyIcon): boolean;
function addCollection(data: IconifyJSON, provider?: string): boolean;

Storage Management

API Loading

Functions for loading icon data from the Iconify API, including batch loading and custom providers.

function loadIcons(
  icons: string[], 
  callback?: IconifyIconLoaderCallback
): IconifyIconLoaderAbort;

function loadIcon(icon: string): Promise<IconifyIcon>;

function addAPIProvider(
  provider: string, 
  config: PartialIconifyAPIConfig
): boolean;

function setCustomIconLoader(loader: IconifyCustomIconLoader): void;

function setCustomIconsLoader(loader: IconifyCustomIconsLoader): void;

API Loading

Icon Transformation & Building

Utility functions for building and transforming SVG content from icon data.

function buildIcon(
  icon: IconifyIcon, 
  customisations?: IconifyIconCustomisations
): IconifyIconBuildResult;

function replaceIDs(
  body: string, 
  prefix?: string | (() => string)
): string;

function calculateSize(
  size: IconifyIconSize, 
  ratio: number, 
  precision?: number
): IconifyIconSize;

Transformation & Building

Offline Usage

Specialized components and functions for offline icon usage without API dependencies.

// Offline versions (from @iconify/react/offline)
const Icon: React.ForwardRefExoticComponent<IconProps & React.RefAttributes<IconElement>>;
const InlineIcon: React.ForwardRefExoticComponent<IconProps & React.RefAttributes<IconElement>>;

function addIcon(name: string, data: IconifyIcon): void;
function addCollection(data: IconifyJSON, prefix?: string | boolean): void;

Offline Usage

Internal API

Low-level API functions for advanced use cases and custom integrations.

interface IconifyAPIInternalFunctions {
  getAPIConfig(provider: string): IconifyAPIConfig | undefined;
  setAPIModule(provider: string, module: IconifyAPIModule): void;
  sendAPIQuery(provider: string, data: IconifyAPIQueryParams, callback: Function): void;
  setFetch(fetch: Function): void;
  getFetch(): Function;
  listAPIProviders(): string[];
}

// Internal API access
const _api: IconifyAPIInternalFunctions;

Types

// Core Types
type IconifyRenderMode = 'style' | 'bg' | 'mask' | 'svg';
type IconElement = SVGSVGElement | HTMLSpanElement;
type IconifyIconOnLoad = (name: string) => void;

// Icon Data Types
interface IconifyIcon {
  body: string;
  width?: number;
  height?: number;
  left?: number;
  top?: number;
  hFlip?: boolean;
  vFlip?: boolean;
  rotate?: number;
}

interface IconifyJSON {
  prefix: string;
  icons: Record<string, IconifyIcon>;
  aliases?: Record<string, Partial<IconifyIcon> & { parent: string }>;
  width?: number;
  height?: number;
  left?: number;
  top?: number;
  hFlip?: boolean;
  vFlip?: boolean;
  rotate?: number;
}

// Customization Types
interface IconifyIconCustomisations {
  width?: IconifyIconSize;
  height?: IconifyIconSize;
  hFlip?: boolean;
  vFlip?: boolean;
  rotate?: string | number;
  inline?: boolean;
}

type IconifyIconSize = number | string;

// API Types
interface PartialIconifyAPIConfig {
  resources: string[];
  index?: number;
  timeout?: number;
  rotate?: number;
  random?: boolean;
  dataAfterTimeout?: boolean;
}

interface IconifyIconBuildResult {
  attributes: Record<string, string>;
  body: string;
}

type IconifyIconLoaderCallback = (
  loaded: IconifyIconName[],
  missing: IconifyIconName[],
  pending: IconifyIconName[]
) => void;

type IconifyIconLoaderAbort = () => void;

interface IconifyIconName {
  provider: string;
  prefix: string;
  name: string;
}

// API Module Types
interface IconifyAPIModule {
  prepare: IconifyAPIPrepareIconsQuery;
  send: IconifyAPISendQuery;
}

type IconifyAPIPrepareIconsQuery = (
  provider: string,
  prefix: string,
  icons: string[]
) => IconifyAPIQueryParams[];

type IconifyAPISendQuery = (
  host: string,
  params: IconifyAPIQueryParams,
  callback: Function
) => void;

interface IconifyAPIQueryParams {
  type: string;
  provider: string;
  prefix: string;
  icons: string[];
  [key: string]: any;
}

interface IconifyAPIConfig {
  resources: string[];
  index: number;
  timeout: number;
  rotate: number;
  random: boolean;
  dataAfterTimeout: boolean;
}

// Custom Loader Types
type IconifyCustomIconLoader = (
  name: string,
  prefix: string,
  provider: string
) => Promise<IconifyIcon | null>;

type IconifyCustomIconsLoader = (
  names: string[],
  prefix: string,
  provider: string
) => Promise<(IconifyIcon | null)[]>;