React Components

/**
 * Block icon component with middle vertical alignment
 * @param props - Icon properties including icon data/name and customizations
 * @param ref - Forward ref to the rendered SVG or span element
 */
const Icon: React.ForwardRefExoticComponent<IconProps & React.RefAttributes<IconElement>>;

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

// Basic usage with icon name
<Icon icon="mdi:home" />

// With custom dimensions
<Icon icon="mdi:home" width="32" height="32" />

// With color (monotone icons only)
<Icon icon="mdi:home" color="blue" />

// With rotation (quarter-turns)
<Icon icon="mdi:home" rotate={1} />

// With rotation (degrees)
<Icon icon="mdi:home" rotate="45deg" />

// With flip transformations
<Icon icon="mdi:home" hFlip={true} />
<Icon icon="mdi:home" flip="horizontal,vertical" />

// With CSS properties
<Icon 
  icon="mdi:home" 
  style={{ margin: '10px' }}
  className="my-icon"
/>

// With fallback content
<Icon 
  icon="might-not-exist:icon" 
  fallback={<span>Loading...</span>}
/>

// With load callback (API mode only)
<Icon 
  icon="mdi:home" 
  onLoad={(name) => console.log(`Icon ${name} loaded`)}
/>

/**
 * Inline icon component with baseline vertical alignment
 * Adds verticalAlign: -0.125em style for proper text alignment
 * @param props - Icon properties including icon data/name and customizations
 * @param ref - Forward ref to the rendered SVG or span element
 */
const InlineIcon: React.ForwardRefExoticComponent<IconProps & React.RefAttributes<IconElement>>;

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

// Inline with text
<p>
  Welcome to your <InlineIcon icon="mdi:home" /> home page
</p>

// In buttons
<button>
  <InlineIcon icon="mdi:plus" /> Add Item
</button>

// All Icon props work with InlineIcon
<InlineIcon 
  icon="mdi:heart" 
  color="red" 
  width="16" 
  height="16" 
/>

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

interface IconifyIconProps extends IconifyIconCustomisations {
  /** The icon to render - either icon data object or icon name string */
  icon: IconifyIcon | string;
  
  /** Rendering mode for the icon */
  mode?: IconifyRenderMode;
  
  /** Icon color (for monotone icons only) */
  color?: string;
  
  /** Flip transformation shorthand */
  flip?: string;
  
  /** Unique identifier for the icon */
  id?: string;
  
  /** Server-side rendering mode */
  ssr?: boolean;
  
  /** Fallback content while icon is loading or failed to load */
  fallback?: React.ReactNode;
  
  /** Callback fired when icon data is loaded from API */
  onLoad?: IconifyIconOnLoad;
}

interface IconifyIconCustomisations {
  /** Icon width */
  width?: IconifyIconSize;
  
  /** Icon height */
  height?: IconifyIconSize;
  
  /** Horizontal flip */
  hFlip?: boolean;
  
  /** Vertical flip */
  vFlip?: boolean;
  
  /** Rotation - number for quarter-turns or string with units */
  rotate?: string | number;
  
  /** Display mode - true for inline, false for block */
  inline?: boolean;
}

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

interface IconifyIcon {
  /** SVG content inside <svg> element */
  body: string;
  
  /** Icon width (default: 16) */
  width?: number;
  
  /** Icon height (default: 16) */
  height?: number;
  
  /** Left offset */
  left?: number;
  
  /** Top offset */
  top?: number;
  
  /** Horizontal flip */
  hFlip?: boolean;
  
  /** Vertical flip */
  vFlip?: boolean;
  
  /** Rotation in quarter-turns */
  rotate?: number;
}

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

const customIcon: IconifyIcon = {
  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
};

<Icon icon={customIcon} />

// Enable SSR mode to render immediately without waiting for mount
<Icon icon="mdi:home" ssr={true} />

// Provide fallback for icons that might not load on server
<Icon 
  icon="mdi:home" 
  ssr={true}
  fallback={<span className="icon-placeholder" />}
/>

// Default SVG rendering (recommended)
<Icon icon="mdi:home" mode="svg" />

// CSS background-image rendering
<Icon icon="mdi:home" mode="bg" />

// CSS mask-image rendering (for monotone icons)
<Icon icon="mdi:home" mode="mask" />

// Auto-detect between bg/mask based on icon content
<Icon icon="mdi:home" mode="style" />

import { useRef } from 'react';
import { Icon } from "@iconify/react";

function MyComponent() {
  const iconRef = useRef<SVGSVGElement>(null);
  
  const handleClick = () => {
    if (iconRef.current) {
      iconRef.current.style.transform = 'scale(1.2)';
    }
  };
  
  return (
    <Icon 
      ref={iconRef}
      icon="mdi:home" 
      onClick={handleClick}
    />
  );
}