---
name: moai-icons-vector
version: 4.0.0
status: stable
tier: domain
description: Vector icon libraries ecosystem guide covering 10+ major libraries with
  200K+ icons, including React Icons (35K+), Lucide (1000+), Tabler Icons (5900+),
  Iconify (200K+), Heroicons, Phosphor, and Radix Icons with implementation patterns,
  decision trees, and best practices.
allowed-tools: Read, Bash, WebSearch, WebFetch, mcp__context7__resolve-library-id,
  mcp__context7__get-library-docs
primary-agent: frontend-expert
secondary-agents:
- ui-ux-expert
- qa-validator
- alfred
keywords:
- icons
- vector icons
- lucide
- react icons
- tabler icons
- phosphor icons
- heroicons
- radix icons
- iconify
- svg icons
- icon library
- icon design system
- accessibility
tags:
- domain-expert
- enterprise
orchestration: null
can_resume: true
typical_chain_position: middle
depends_on: []
updated: '2025-11-18'
stability: stable
---


# moai-icons-vector

**Vector Icon Libraries: Enterprise Guide (10+ Libraries, 200K+ Icons)**

> **Primary Agent**: frontend-expert
> **Secondary Agent**: ui-ux-expert
> **Version**: 4.0.0 (Lucide v0.4+, React Icons 35K+, Tabler v2.0+, Phosphor v1.4+)
> **Keywords**: icons, vector icons, lucide, react icons, iconify, svg icons, accessibility

## Level 1: Quick Reference

### Library Selection Guide

**Ecosystem Leaders (1000+ icons)**:
- **Lucide** (1000+): General UI, modern design, ~30KB
- **React Icons** (35K+): Multi-library support, modular bundles
- **Tabler Icons** (5900+): Dashboard optimized, ~22KB
- **Ionicons** (1300+): Mobile + web compatibility

**Specialist Libraries (300-800 icons)**:
- **Heroicons** (300+): Official Tailwind CSS icons
- **Phosphor** (800+): 6 weights + duotone variations
- **Material Design** (900+): Google design system
- **Bootstrap Icons** (2000+): Bootstrap ecosystem

**Compact & Specialized**:
- **Radix Icons** (150+): Precise 15x15px, ~5KB
- **Simple Icons** (3300+): Brand logos only
- **Iconify** (200K+): Universal framework, CDN-based

### Quick Decision Matrix

| Scenario | Best Choice | Why |
|----------|-------------|-----|
| Want maximum icons | Iconify | 200K+ icons from 150+ sets |
| Dashboard application | Tabler Icons | 5900 optimized icons, 24px |
| Tailwind CSS project | Heroicons | Official integration |
| Flexible styling needed | Phosphor | 6 weights + duotone |
| Minimal bundle size | Radix Icons | 5KB, precise 15x15px |
| Brand logos | Simple Icons | 3300+ company logos |
| General purpose UI | Lucide | 1000+ modern, well-designed |

### Bundle Size Comparison

```
Radix Icons:        ~5KB   (150 icons)
Heroicons:         ~10KB  (300 icons)
Tabler Icons:      ~22KB  (5900 icons)
Ionicons:          ~25KB  (1300 icons)
Phosphor:          ~25KB  (800 icons with weights)
Lucide:            ~30KB  (1000 icons)
Simple Icons:      ~50KB  (3300+ brand icons)
React Icons:   Modular (varies by library)
```

## Level 2: Practical Implementation

### Core Library Patterns

#### Lucide React - General Purpose (1000+ icons)

```tsx
import { Heart, Search, Settings, ChevronRight } from 'lucide-react'

export function LucideExample() {
  return (
    <div className="space-y-4">
      {/* Basic usage (24px default) */}
      <div className="flex items-center gap-2">
        <Search />
        <span>Search</span>
      </div>

      {/* Custom styling */}
      <Heart size={32} color="#ff0000" fill="#ff0000" />

      {/* Tailwind integration */}
      <Settings className="w-6 h-6 text-gray-500 hover:text-gray-900" />

      {/* Icon button */}
      <button className="p-2 rounded-lg hover:bg-gray-100">
        <ChevronRight size={20} />
      </button>
    </div>
  )
}
```

#### React Icons - Multi-Library (35K+ icons)

```tsx
import { FaHome } from "react-icons/fa"        // Font Awesome
import { MdHome } from "react-icons/md"        // Material Design
import { BsHouse } from "react-icons/bs"       // Bootstrap
import { FiHome } from "react-icons/fi"        // Feather
import { SiReact } from "react-icons/si"       // Brand logos

export function MultiLibraryExample() {
  return (
    <div className="flex gap-4">
      <FaHome size={32} className="text-blue-600" />
      <MdHome size={32} className="text-green-600" />
      <BsHouse size={32} className="text-purple-600" />
      <FiHome size={32} className="text-orange-600" />
      <SiReact size={32} className="text-cyan-500" />
    </div>
  )
}
```

#### Phosphor Icons - Weight Variations (800+ icons)

```tsx
import { Heart, Star } from "@phosphor-icons/react"

export function PhosphorExample() {
  const [rating, setRating] = React.useState(3)

  return (
    <div className="space-y-4">
      {/* Weight variations */}
      <div className="flex gap-2">
        <Heart weight="thin" />
        <Heart weight="light" />
        <Heart weight="regular" />
        <Heart weight="bold" />
        <Heart weight="fill" />
      </div>

      {/* Interactive rating */}
      <div className="flex gap-1">
        {[1, 2, 3, 4, 5].map((star) => (
          <button key={star}>
            <Star
              weight={star <= rating ? "fill" : "regular"}
              size={24}
              color={star <= rating ? "#fbbf24" : "#d1d5db"}
            />
          </button>
        ))}
      </div>
    </div>
  )
}
```

#### Iconify - Universal Framework (200K+ icons)

```tsx
import { Icon } from "@iconify/react"

export function IconifyExample() {
  return (
    <div className="space-y-4">
      {/* String-based (CDN loaded) */}
      <Icon icon="fa:home" width="32" height="32" />
      <Icon icon="mdi:account" width="32" height="32" />
      <Icon icon="bi:house" width="32" height="32" />

      {/* Custom styling */}
      <Icon
        icon="heroicons:heart"
        width="48"
        height="48"
        style={{ color: "#ef4444" }}
      />
    </div>
  )
}
```

### Type-Safe Icon Button

```tsx
import { FC, SVGProps } from 'react'

type IconType = FC<SVGProps<SVGSVGElement>>

interface IconButtonProps {
  icon: IconType
  label: string
  variant?: 'primary' | 'secondary' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
  onClick?: () => void
}

const sizeMap = {
  sm: 'w-4 h-4',
  md: 'w-5 h-5',
  lg: 'w-6 h-6',
}

const variantMap = {
  primary: 'bg-blue-500 text-white hover:bg-blue-600',
  secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300',
  ghost: 'text-gray-600 hover:text-gray-900 hover:bg-gray-100',
}

export function IconButton({
  icon: Icon,
  label,
  variant = 'ghost',
  size = 'md',
  onClick,
}: IconButtonProps) {
  return (
    <button
      onClick={onClick}
      aria-label={label}
      title={label}
      className={`
        p-2 rounded-lg transition-all
        ${variantMap[variant]}
      `}
    >
      <Icon className={sizeMap[size]} />
    </button>
  )
}
```

## Level 3: Advanced Integration

### Custom Icon Component

```tsx
import { forwardRef, SVGProps } from 'react'

interface CustomIconProps extends SVGProps<SVGSVGElement> {
  isActive?: boolean
  tooltip?: string
}

export const CustomIcon = forwardRef<SVGSVGElement, CustomIconProps>(
  ({ isActive, tooltip, className = '', ...props }, ref) => (
    <svg
      ref={ref}
      viewBox="0 0 24 24"
      width="24"
      height="24"
      className={`
        ${isActive ? 'text-blue-500' : 'text-gray-400'}
        ${tooltip ? 'cursor-help' : ''}
        ${className}
        transition-colors duration-200
      `}
      title={tooltip}
      {...props}
    >
      <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2z" />
    </svg>
  )
)
```

### Icon Theme System

```tsx
import { Heart, Settings } from 'lucide-react'

type IconTheme = 'light' | 'dark' | 'accent'

interface IconThemeConfig {
  color: string
  strokeWidth: number
  opacity: number
}

const themeConfig: Record<IconTheme, IconThemeConfig> = {
  light: { color: '#e5e7eb', strokeWidth: 2, opacity: 1 },
  dark: { color: '#1f2937', strokeWidth: 2, opacity: 1 },
  accent: { color: '#0ea5e9', strokeWidth: 2.5, opacity: 1 },
}

export function ThemedIcon({ theme, size = 24 }: { theme: IconTheme; size?: number }) {
  const config = themeConfig[theme]

  return (
    <div className="flex gap-4">
      <Heart size={size} color={config.color} strokeWidth={config.strokeWidth} />
      <Settings size={size} color={config.color} strokeWidth={config.strokeWidth} />
    </div>
  )
}
```

### Icon Animation

```tsx
import { Heart } from 'lucide-react'
import { useState } from 'react'

export function AnimatedIcon() {
  const [isActive, setIsActive] = useState(false)

  return (
    <button onClick={() => setIsActive(!isActive)} className="p-4">
      <Heart
        size={32}
        className={`
          text-red-500 transition-all duration-300
          ${isActive ? 'scale-125 animate-pulse' : 'scale-100'}
        `}
        fill={isActive ? '#ff0000' : 'none'}
      />
    </button>
  )
}
```

## Performance & Best Practices

### Performance Optimization

```tsx
// ✅ Good: Tree-shake specific icons
import { Heart, Star } from 'lucide-react'

// ❌ Bad: Import entire library
import * as Icons from 'lucide-react'
const Icon = Icons[iconName]

// ✅ Good: Dynamic imports for large sets
const LazyIcon = React.lazy(() => import('lucide-react').then(module => ({
  default: module[iconName]
})))

// ✅ Good: Memoize components
const MemoHeart = React.memo(Heart)
```

### Bundle Optimization Strategies

1. **Choose right library size**: Use Radix Icons for minimal bundles
2. **Import specific icons**: Avoid `import *` patterns
3. **Dynamic loading**: Load icons on-demand for large sets
4. **Icon subsets**: Create custom bundles per feature
5. **Tree-shaking**: Use ES modules and bundler optimization

### Accessibility Essentials

- ✅ Use `aria-label` for icon-only buttons
- ✅ Ensure 4.5:1 color contrast ratio
- ✅ Support high contrast mode with `currentColor`
- ✅ Don't rely on color alone for meaning
- ✅ Use semantic HTML structure
- ✅ Test with screen readers

## Library Comparison Summary

| Library | Icons | Bundle Size | Best For |
|---------|-------|-------------|----------|
| **Lucide** | 1000+ | ~30KB | General purpose UI |
| **Heroicons** | 300+ | ~10KB | Tailwind CSS projects |
| **Phosphor** | 800+ | ~25KB | Weight flexibility needed |
| **Tabler** | 5900+ | ~22KB | Dashboard applications |
| **Radix** | 150+ | ~5KB | Minimal bundle size |
| **React Icons** | 35K+ | Modular | Multi-library support |
| **Iconify** | 200K+ | CDN | Maximum icon variety |

## Quick Installation Commands

```bash
# Core libraries
npm install lucide-react
npm install @heroicons/react
npm install @phosphor-icons/react
npm install @tabler/icons-react
npm install @radix-ui/react-icons

# Multi-library support
npm install react-icons
npm install @iconify/react

# Brand icons
npm install simple-icons
```

---

**Version**: 4.0.0 Enterprise
**Last Updated**: 2025-11-13
**Status**: Production Ready
**Enterprise Grade**: ✅ Full Enterprise Support