iconpackr 📦

A CLI tool to convert SVG files into React icon components that seamlessly integrate with Ant Design projects.

Features

• 🔍 Recursive SVG Scanning - Automatically discovers all SVG files in a directory
• 🎨 Ant Design Compatible - Generated components work with @ant-design/icons props
• 📐 Smart Size Conversion - Converts SVG dimensions to em units (based on 16px base font)
• 🎯 Style Props Support - Control icon size via fontSize and color via color style props
• 🌈 Smart Color Handling - Automatically detects single-color vs multi-color icons
• 📁 Directory-based Grouping - Organizes icons by source directory structure
• 🔤 Auto Naming - Converts file paths to PascalCase component names
• 👀 Interactive Preview - Built-in preview server with customization drawer
• 📋 One-click Copy - Copy React code directly from the preview page

Installation

# Using pnpm
pnpm add -D iconpackr

# Using npm
npm install -D iconpackr

# Using yarn
yarn add -D iconpackr

Requirements

• Node.js >= 18
• React project with @ant-design/icons installed

Usage

Generate Icon Components

iconpackr generate --source <svg-directory> --output <output-directory> --overwrite

Options:

• -s, --source <path> - Source directory containing SVG files (required)
• -o, --output <path> - Output directory for generated components (required)
• --overwrite - Overwrite existing files without prompting

Example:

iconpackr generate --source ./assets/icons --output ./src/icons

Preview Icons

iconpackr preview --dir <icons-directory>

Options:

• -d, --dir <path> - Directory containing generated icon components (required)
• -p, --port <number> - Port for the preview server (default: 3567)

Example:

iconpackr preview --dir ./src/icons --port 3000

Generated Component Structure

Each SVG file is converted to a TypeScript React component:

import React from 'react';
import Icon from '@ant-design/icons';
import type { CustomIconComponentProps } from '@ant-design/icons/lib/components/Icon';

interface MyIconProps extends Partial<CustomIconComponentProps> {
  width?: string | number;
  height?: string | number;
}

const MyIconSvg: React.FC<{ width?: string | number; height?: string | number }> = ({ 
  width = '1.5em',  // Derived from SVG: 24px / 16px = 1.5em
  height = '1.5em' 
}) => (
  <svg viewBox="0 0 24 24" width={width} height={height} fill="currentColor">
    {/* SVG content */}
  </svg>
);

const MyIcon: React.FC<MyIconProps> = ({ width, height, ...props }) => (
  <Icon component={() => <MyIconSvg width={width} height={height} />} {...props} />
);

export default MyIcon;

Using Generated Icons

Basic Usage

import { HomeIcon, SettingsIcon } from './icons';

function App() {
  return (
    <div>
      <HomeIcon />
      <SettingsIcon />
    </div>
  );
}

Customizing Size

Icons scale with the parent's font size. You can also use the style prop:

// Using fontSize style prop
<HomeIcon style={{ fontSize: 24 }} />
<HomeIcon style={{ fontSize: 32 }} />
<HomeIcon style={{ fontSize: 48 }} />

// Inherits from parent font size
<div style={{ fontSize: 24 }}>
  <HomeIcon /> {/* Will be 24px */}
</div>

Customizing Color

// Using color style prop
<HomeIcon style={{ color: 'red' }} />
<HomeIcon style={{ color: '#1890ff' }} />
<HomeIcon style={{ color: 'rgb(82, 196, 26)' }} />

// Inherits from parent color
<div style={{ color: 'blue' }}>
  <HomeIcon /> {/* Will be blue */}
</div>

Combined Styling

<HomeIcon style={{ fontSize: 32, color: '#1890ff' }} />

Size Conversion

iconpackr automatically converts SVG dimensions to em units using 16px as the base font size:

| SVG Size | Generated Default | |----------|-------------------| | 16px | 1em | | 24px | 1.5em | | 32px | 2em | | 48px | 3em |

If the SVG doesn't have explicit width/height attributes, the dimensions are extracted from the viewBox attribute.

Smart Color Handling

iconpackr intelligently analyzes the colors in your SVG files and handles them differently based on whether the icon is monochrome (single color) or multi-color.

How It Works

1. Color Analysis: When processing an SVG, iconpackr extracts all fill and stroke color values
2. Single Color Detection: If only one unique color is found (excluding none, transparent, currentColor), the icon is considered monochrome
3. Color Conversion:
   • Monochrome icons: All colors are converted to currentColor, enabling runtime color customization
   • Multi-color icons: Original colors are preserved as-is

Monochrome Icons (Single Color)

For icons with a single color, iconpackr:

• Converts the color to currentColor for runtime customization
• Stores the original color in a data-original-color attribute
• Enables color picker in the preview page

// Original SVG with single color (#1A7F49)
<svg fill="#1A7F49">...</svg>

// Generated component - color converted to currentColor
<svg fill="currentColor" data-original-color="#1a7f49">...</svg>

// Usage - color can be customized at runtime
<MyIcon style={{ color: '#1890ff' }} />

Multi-Color Icons

For icons with multiple colors, iconpackr:

• Preserves all original colors exactly as defined
• Disables the color picker in the preview page (shows a notice)
• The icon renders with its original colors

// Original SVG with multiple colors
<svg>
  <circle fill="#FF5733" />
  <path stroke="#33FF57" />
  <circle fill="#3357FF" />
</svg>

// Generated component - colors preserved
<svg>
  <circle fill="#FF5733" />
  <path stroke="#33FF57" />
  <circle fill="#3357FF" />
</svg>

// Usage - colors cannot be changed via style prop
<MyMultiColorIcon /> // Renders with original colors

Preview Page Behavior

| Icon Type | Color Picker | Default Color | Behavior | |-----------|--------------|---------------|----------| | Monochrome | ✅ Enabled | Original color | Can customize color | | Multi-color | ❌ Disabled | N/A | Shows "cannot recolor" notice |

In the preview page:

• Monochrome icons display with their original color by default, and you can change the color using the color picker
• Multi-color icons display with their original colors, and the color picker is disabled with a notice explaining that the icon has multiple colors

Naming Convention

File paths and names are automatically converted to PascalCase component names:

| File Path | Component Name | |-----------|----------------| | home.svg | HomeIcon | | arrow-left.svg | ArrowLeftIcon | | user_profile.svg | UserProfileIcon | | common/settings.svg | CommonSettingsIcon | | nav/arrow-right.svg | NavArrowRightIcon |

⚠️ Important: Hyphens (-), underscores (_), and dots (.) in file names and paths are stripped during conversion. This means different file names may generate the same component name and cause overwrites:

| File Names | Generated Component | |------------|---------------------| | arrow-left.svg | ArrowLeftIcon | | arrow_left.svg | ArrowLeftIcon ⚠️ Same! | | arrowleft.svg | ArrowleftIcon |

Make sure your SVG file names are unique after removing these separators.

Preview Server Features

The built-in preview server provides:

• 🔍 Search - Filter icons by name
• 📂 Grouping - Icons organized by source directory
• 🌈 Original Colors - Icons display with their original colors in the list view
• 🎨 Customization Drawer - Click any icon to:
  • Adjust font size (12px - 128px)
  • Pick colors from presets or custom color picker (monochrome icons only)
  • See live preview with original color as default
  • Copy generated React code
• 🚫 Smart Color Picker - Automatically disabled for multi-color icons with explanation
• 📋 One-click Copy - Copy component usage code to clipboard

Output Structure

output-directory/
├── HomeIcon.tsx
├── SettingsIcon.tsx
├── ArrowLeftIcon.tsx
├── index.ts          # Exports all icons
└── README.md         # Usage instructions

License

MIT