FlexiSVG

SVG sprite generator with automatic TypeScript type generation for React projects.

Features

• Two Icon Variants: Dynamic and Resizable icons
• Automatic Sprite Generation: Combines multiple SVG files into a single optimized sprite
• TypeScript Support: Auto-generated type-safe Icon component with .ts config file support
• Optimized: Uses SVGO for SVG optimization
• Easy Integration: Simple CLI commands for initialization and generation

Installation

# npm
npm install -D flexisvg

# pnpm
pnpm add -D flexisvg

Quick Start

1. Initialize Project

Run the init command to create configuration file and folder structure:

# npm
npx flexisvg init

# pnpm
pnpm dlx flexisvg init

This will create:

• flexisvg.config.ts - Configuration file
• public/icons/dynamic/ - Dynamic icons folder
• public/icons/resizable/ - Resizable icons folder
• src/components/ - Output folder for Icon component

2. Add SVG Files

Place your SVG files in the appropriate folders:

• dynamic: Icons with customizable size and color (colors converted to currentColor)
• resizable: Icons with customizable size only (keeps original colors)

3. Generate Sprite

Run the generate command to create sprite and Icon component:

npx flexisvg

This will generate:

• public/icons/sprite.svg - Optimized SVG sprite
• src/components/icon/index.tsx - Type-safe React Icon component

Configuration

The flexisvg.config.ts file allows you to customize the folder structure:

import { SpriteGeneratorConfig } from 'flexisvg';

const config: SpriteGeneratorConfig = {
  // Input directories
  dynamicDir: 'public/icons/dynamic',
  resizableDir: 'public/icons/resizable',

  // Output paths
  outputSpriteDir: 'public/icons',
  outputComponentPath: 'src/components/icon/index.tsx',
};

export default config;

Configuration Options

Option	Type	Description
dynamicDir	string	Directory for dynamic icons (customizable size and color)
resizableDir	string	Directory for resizable icons (customizable size only)
outputSpriteDir	string	Output directory for sprite.svg
outputComponentPath	string	Output path for Icon component

Icon Variants

Dynamic Icons

• Use case: Icons that need both size and color customization
• Processing:
  • Converts all colors to currentColor (inherits CSS color property)
  • Removes fill and stroke attributes with values none, black, or #000000
  • SVG <symbol> automatically handles size via viewBox
• Example: UI icons, action buttons

public/icons/dynamic/
  ├─ home.svg
  ├─ user.svg
  └─ settings.svg

Before processing:

<svg fill="none" viewBox="0 0 24 24">
  <path fill="#7C868F" d="M12..." />
</svg>

After processing:

<symbol fill="none" viewBox="0 0 24 24" id="home">
  <path fill="currentColor" d="M12..." />
</symbol>

Resizable Icons

• Use case: Icons that need size customization but should keep original colors
• Processing: Only converts to <symbol> format, preserves all original colors
• Example: Colored illustrations, multi-color icons, brand logos

public/icons/resizable/
  ├─ illustration-1.svg
  ├─ colored-icon.svg
  └─ brand-logo.svg

Generated Output

1. Sprite File (public/icons/sprite.svg)

An optimized SVG sprite containing all icons as symbols:

<svg xmlns="http://www.w3.org/2000/svg">
  <symbol id="home" viewBox="0 0 24 24">
    <!-- SVG content -->
  </symbol>
  <symbol id="user" viewBox="0 0 24 24">
    <!-- SVG content -->
  </symbol>
  <!-- More symbols... -->
</svg>

2. Icon Component (src/components/icon/index.tsx)

A type-safe React component with auto-generated types:

// Auto-generated types
export type DynamicIconId = 'home' | 'user' | 'settings';
export type ResizableIconId = 'illustration-1' | 'colored-icon' | 'brand-logo';
export type IconId = DynamicIconId | ResizableIconId;

// Icon component
export const Icon = ({ id, size = 24, ...props }: IconProps) => {
  return (
    <svg width={size} height={size} {...props}>
      <use href={`/sprite.svg#${id}`} />
    </svg>
  );
};

Usage in Your App

Basic Usage

import { Icon } from '@/components/icon';

function App() {
  return (
    <div>
      {/* Default size (24px) */}
      <Icon id="home" />

      {/* Custom size */}
      <Icon id="user" size={32} />

      {/* With custom color (for dynamic icons) */}
      <Icon id="settings" size={20} style={{ color: 'blue' }} />

      {/* With additional props */}
      <Icon id="logo" className="my-icon" onClick={handleClick} />
    </div>
  );
}

TypeScript Benefits

The generated types provide autocomplete and type checking:

// ✅ Valid - 'home' exists in icon set
<Icon id="home" />

// ❌ TypeScript error - 'nonexistent' is not a valid icon id
<Icon id="nonexistent" />

CLI Commands

flexisvg init

Creates configuration file and folder structure.

npx flexisvg init

flexisvg

Generates sprite and Icon component based on configuration.

npx flexisvg

Custom Config Path

Use a custom configuration file:

npx flexisvg --config path/to/custom.config.js

License

MIT