A CLI tool for fetching and generating type-safe React icon components from the extensive Iconify icon library.

@saas-js/iconify

A CLI tool for fetching and generating type-safe React icon components from the extensive Iconify icon library.

About

@saas-js/iconify allows you to:

🚀 Generate React components from 200,000+ icons across 150+ icon sets
📝 Full TypeScript support with proper types and interfaces
⚙️ Configurable output directory, icon sizes, and aliases
🔧 CLI and MCP (Model Context Protocol) server support
🎨 Customizable icon size with runtime override support
🏷️ Icon aliasing for better naming conventions

This package wouldn't be possible without the great work of Vjacheslav Trushkin.

Why does this exist?

Problems with existing solutions:

Iconify web components require an internet connection and don't work offline
react-icons is heavy (~2MB+), has poor tree-shaking, and causes performance issues in Next.js
Icon fonts are outdated, not accessible, and hard to customize
Manual SVG copying or sprites is tedious and hard to maintain

Our approach:

Similar to shadcn/ui or sly-cli, we generate the actual source code that you own and control. But instead of a limited set of components, you get access to 200,000+ icons from the entire Iconify ecosystem.

Benefits:

✅ RSC - Works with React Server Components
✅ Offline-first - Icons work without internet connection
✅ Perfect tree-shaking - Only bundle the icons you actually use
✅ Full ownership - Generated code lives in your codebase
✅ Type-safe - Complete TypeScript support with proper interfaces
✅ Massive library - 150+ icon sets vs limited selection in other tools

While there are definitely downsides to using SVG-in-JS, we feel like the benefits outweigh the cons when building React apps and only use a dozen of icons on any screen.

Quick Start

Initialize configuration:
```
icons init
```

Add icons to your project:

# With explicit icon set
icons add --set lucide home user settings

# Using default icon set (if configured)
icons add home user settings

Use generated components:

import { HomeIcon } from './components/icons/home-icon'
import { SettingsIcon } from './components/icons/settings-icon'
import { UserIcon } from './components/icons/user-icon'

function App() {
  return (
    <div>
      <HomeIcon size="24px" />
      <UserIcon className="text-blue-500" />
      <SettingsIcon size="1.5rem" />
    </div>
  )
}

Popular Icon Sets

Iconify React supports all icon sets available in the Iconify library. Popular choices include:

Lucide (lucide) - Modern, clean icons
Heroicons (heroicons) - Tailwind CSS icons
Tabler Icons (tabler) - Free SVG icons
Feather (feather) - Simple, beautiful icons
Phosphor (phosphor) - Flexible icon family
Material Design Icons (mdi) - Google's Material Design
Font Awesome (fa-solid, fa-regular, fa-brands) - Popular icon library

Browse all available icons at Iconify Icon Sets.

Generated Components

Each generated component includes:

import React from 'react'

export interface HomeIconProps extends React.SVGProps<SVGSVGElement> {
  size?: number | string
}

/**
 * home
 * Lucide
 * @url https://icon-sets.iconify.design/lucide
 * @license MIT
 * @version 1.0.0
 */
export const HomeIcon: React.FC<HomeIconProps> = ({
  size = '1em',
  ...props
}) => {
  return (
    <svg
      width={size}
      height={size}
      viewBox="0 0 24 24"
      fill="none"
      xmlns="http://www.w3.org/2000/svg"
      {...props}
    >
      {/* SVG content */}
    </svg>
  )
}

TypeScript Support

All generated components are fully typed with:

Proper TypeScript interfaces
SVG props inheritance
Size prop with string or number support
JSDoc comments with icon metadata

Overview