Skip to Content
Documentation
Starter kits
Utilities
Get Pro
Overview
Getting Started
Installation
Basic Usage
Reference
CLI Reference
Configuration
Icon Sets

Basic Usage

Learn how to use Iconx to generate React icon components

Basic Usage

Initialize Configuration

First, initialize your project with a configuration file:

icons init

This creates an icons.json file in your project root with default settings:

{
  "$schema": "https://saas-js.dev/icons/schema.json",
  "outputDir": "/src/components/icons",
  "defaultIconSet": "lucide",
  "iconSize": "1em",
  "aliases": {}
}

Add Icons

Add icons to your project using the add command:

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

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

# Short flag
icons add -s heroicons home user settings

Use Generated Components

After adding icons, you can import and use them in your React components:

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

function Navigation() {
  return (
    <nav>
      <a href="/home">
        <HomeIcon size="20px" />
        Home
      </a>
      <a href="/profile">
        <UserIcon className="text-blue-500" size="1.2em" />
        Profile
      </a>
      <a href="/settings">
        <SettingsIcon size={24} />
        Settings
      </a>
    </nav>
  )
}

Component Props

All generated components accept standard SVG props plus a size prop:

<HomeIcon
  size="24px" // Size (string or number)
  className="text-gray-500" // CSS classes
  onClick={handleClick} // Event handlers
  fill="currentColor" // SVG attributes
  stroke="none"
  {...otherProps} // Any other SVG props
/>

Size Prop

The size prop accepts various formats:

<HomeIcon size="16px" />    // Pixels
<HomeIcon size="1.5rem" />  // Rem units
<HomeIcon size="2em" />     // Em units
<HomeIcon size={24} />      // Number (pixels)
<HomeIcon size="100%" />    // Percentage

Common Examples

import {
  HomeIcon,
  LogOutIcon,
  SettingsIcon,
  UserIcon,
} from './components/icons'

function Sidebar() {
  return (
    <aside className="w-64 bg-gray-100">
      <nav className="p-4 space-y-2">
        <a
          href="/dashboard"
          className="flex items-center gap-3 p-2 rounded hover:bg-gray-200"
        >
          <HomeIcon size="20px" />
          Dashboard
        </a>
        <a
          href="/profile"
          className="flex items-center gap-3 p-2 rounded hover:bg-gray-200"
        >
          <UserIcon size="20px" />
          Profile
        </a>
        <a
          href="/settings"
          className="flex items-center gap-3 p-2 rounded hover:bg-gray-200"
        >
          <SettingsIcon size="20px" />
          Settings
        </a>
        <button className="flex items-center gap-3 p-2 rounded hover:bg-gray-200 w-full text-left">
          <LogOutIcon size="20px" />
          Logout
        </button>
      </nav>
    </aside>
  )
}

Icon Buttons

import { EditIcon, PlusIcon, TrashIcon } from './components/icons'

function ActionButtons() {
  return (
    <div className="flex gap-2">
      <button className="p-2 bg-blue-500 text-white rounded hover:bg-blue-600">
        <PlusIcon size="16px" />
      </button>
      <button className="p-2 bg-gray-500 text-white rounded hover:bg-gray-600">
        <EditIcon size="16px" />
      </button>
      <button className="p-2 bg-red-500 text-white rounded hover:bg-red-600">
        <TrashIcon size="16px" />
      </button>
    </div>
  )
}

Status Indicators

import {
  AlertCircleIcon,
  CheckCircleIcon,
  XCircleIcon,
} from './components/icons'

function StatusMessage({ type, message }) {
  const configs = {
    success: { icon: CheckCircleIcon, color: 'text-green-500' },
    error: { icon: XCircleIcon, color: 'text-red-500' },
    warning: { icon: AlertCircleIcon, color: 'text-yellow-500' },
  }

  const { icon: Icon, color } = configs[type]

  return (
    <div className="flex items-center gap-2">
      <Icon size="20px" className={color} />
      <span>{message}</span>
    </div>
  )
}

Custom Output Directory

You can specify a custom output directory:

# Custom directory for this command
npx iconx add --set lucide --outdir ./src/assets/icons home user

# Or update your icons.json
{
  "outputDir": "./src/assets/icons",
  "defaultIconSet": "lucide"
}

Working with Different Icon Sets

Lucide Icons

npx iconx add --set lucide home user settings mail search

Heroicons

npx iconx add --set heroicons home user cog envelope magnifying-glass

Tabler Icons

npx iconx add --set tabler home user settings mail search

Font Awesome

npx iconx add --set fa-solid home user cog envelope search
npx iconx add --set fa-regular heart star
npx iconx add --set fa-brands github twitter

Best Practices

1. Use Consistent Naming

# Good: Use consistent icon names across sets
npx iconx add --set lucide home user settings
npx iconx add --set heroicons home user cog  # 'cog' instead of 'settings'

2. Organize by Feature

# Add icons for specific features together
npx iconx add --set lucide mail mail-open send reply reply-all  # Email feature
npx iconx add --set lucide user user-plus user-minus user-check  # User management

3. Set Default Icon Set

{
  "defaultIconSet": "lucide"
}

Then you can omit the --set flag:

npx iconx add home user settings

4. Use Aliases for Better Names

{
  "aliases": {
    "house": "home",
    "cog": "settings",
    "user-circle": "profile"
  }
}
# This generates home-icon.tsx instead of house-icon.tsx
npx iconx add house

Next Steps

Next

Introduction
Basic Usage | Saas UI