@lilith/ui-icons

Theme-aware animated icons with distinct Lilith (mystical) and Luxe (elegant) variants. 125+ icons with automatic theme detection, hover animations, and accessibility support.

Features

• 125+ icons across 15+ categories
• Theme-aware - distinct visual styles for Lilith and Luxe themes
• Animated - hover/focus animations with reduced-motion support
• Accessible - proper ARIA labels and keyboard navigation
• Dynamic loading - registry-based icon lookup by name
• Customizable - factory function for creating custom themed icons
• DRY architecture - shared animation and styling logic

Installation

pnpm add @lilith/ui-icons

Peer Dependencies

{
  "react": "^18.0.0",
  "react-dom": "^18.0.0",
  "styled-components": "^6.0.0"
}

Usage

Direct Import

Import specific icons for optimal bundle size:

import { HeartIcon, StarIcon, SparklesIcon } from '@lilith/ui-icons';

function App() {
  return (
    <>
      <HeartIcon size={24} />
      <StarIcon size={32} animated={false} />
      <SparklesIcon size={24} />
    </>
  );
}

Dynamic Icon Component

Load icons by name at runtime:

import { Icon } from '@lilith/ui-icons';

function DynamicIcon({ name }: { name: string }) {
  return <Icon name={name} size={24} />;
}

// Usage
<Icon name="heart" size={24} />
<Icon name="star" size={32} />

Icon Registry

Search and lookup icons programmatically:

import {
  iconRegistry,
  getIconComponent,
  isRegisteredIcon,
  getRegisteredIconNames,
  searchIconsByTag,
} from '@lilith/ui-icons';

// Check if icon exists
if (isRegisteredIcon('heart')) {
  const HeartIcon = getIconComponent('heart');
  // ...
}

// Get all icon names
const allIcons = getRegisteredIconNames();
// ['alert-circle', 'arrow-down', 'heart', ...]

// Search by tag
const socialIcons = searchIconsByTag('social');
// ['heart', 'star', 'thumbs-up', ...]

Animation Triggers

Control when icon animations play:

import { HeartIcon, onHover, always, never, idleMs } from '@lilith/ui-icons';

// Animate on hover (default)
<HeartIcon animationTrigger={onHover} />

// Always animate
<HeartIcon animationTrigger={always} />

// Never animate
<HeartIcon animationTrigger={never} />

// Animate after idle time with optional variance
<HeartIcon animationTrigger={idleMs(3000).withVariance(500)} />

Creating Custom Icons

Use the factory function to create themed icons:

import { createThemedIcon, type ThemeVariantConfig } from '@lilith/ui-icons';

const CustomIcon = createThemedIcon({
  name: 'CustomIcon',
  lilith: {
    render: ({ size, color }) => (
      <svg width={size} height={size}>
        <circle cx={size/2} cy={size/2} r={size/3} fill={color} />
      </svg>
    ),
    animation: 'pulse',
    gradient: 'mystic',
  },
  luxe: {
    render: ({ size, color }) => (
      <svg width={size} height={size}>
        <rect width={size} height={size} fill={color} />
      </svg>
    ),
    animation: 'scale',
  },
});

Icon Categories

Status & Feedback

AlertCircleIcon, AlertSquareIcon, AlertTriangleIcon, CheckCircleIcon, CheckIcon, HelpCircleIcon, InfoIcon, Loader2Icon, XCircleIcon, XIcon, ZapIcon

Navigation

ArrowDownIcon, ArrowLeftIcon, ArrowRightIcon, ArrowUpIcon, ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon, ChevronUpIcon, ExternalLinkIcon, HomeIcon, LinkIcon, MenuIcon

Social & Engagement

HeartIcon, SparklesIcon, StarIcon, ThumbsDownIcon, ThumbsUpIcon, BookmarkIcon, ShareIcon

Commerce & Finance

BanknoteIcon, BitcoinIcon, CoinsIcon, CreditCardIcon, DiamondIcon, DollarSignIcon, GemIcon, GiftIcon, ShoppingBagIcon, ShoppingCartIcon, TicketIcon, WalletIcon

User & Account

LogInIcon, LogOutIcon, UserCheckIcon, UserCircleIcon, UserIcon, UserPlusIcon, UsersIcon

Media Controls

CameraIcon, HeadphonesIcon, MicIcon, MicOffIcon, PauseIcon, PlayIcon, SettingsIcon, SkipBackIcon, SkipForwardIcon, VideoIcon, Volume1Icon, Volume2Icon, VolumeXIcon

Security

EyeIcon, EyeOffIcon, LockIcon, ScaleIcon, ShieldIcon, UnlockIcon

Communication

BellIcon, GlobeIcon, MailIcon, MessageCircleIcon, MessageSquareIcon, PhoneIcon, RadioIcon, SendIcon

Content & Files

CodeIcon, CopyIcon, DownloadIcon, EditIcon, FileTextIcon, FilterIcon, HashIcon, ImageIcon, LayersIcon, LightbulbIcon, PackageIcon, SearchIcon, TagIcon, UploadIcon

Location & Places

Building2Icon, CompassIcon, HospitalIcon, MapIcon, MapPinIcon, ServerIcon, TargetIcon

Time & Calendar

CalendarIcon, ClockIcon

Charts & Data

BarChart3Icon, TrendingDownIcon, TrendingUpIcon

Actions

MaximizeIcon, MinimizeIcon, MinusIcon, MoreHorizontalIcon, MoreVerticalIcon, PlusIcon, RefreshCwIcon, Trash2Icon, TrashIcon

Devices & Tech

BotIcon, LayoutGridIcon, MonitorIcon, SmartphoneIcon

Work & Business

AwardIcon, BriefcaseIcon, PaletteIcon, ShirtIcon

Emotions & Expression

FlameIcon, FrownIcon, HandMetalIcon, SirenIcon

Special & Celebration

PartyPopperIcon, RocketIcon, SnowflakeIcon

Tiers & Ranks

TierBronzeIcon, TierSilverIcon, TierGoldIcon, TierPlatinumIcon, TierDiamondIcon

API Reference

IconProps

Prop	Type	Default	Description
size	number	24	Icon size in pixels
color	string	'currentColor'	Icon color
animated	boolean	true	Enable animations
animationTrigger	AnimationTrigger	onHover	When to animate
className	string	-	Additional CSS class
style	CSSProperties	-	Inline styles
aria-label	string	-	Accessibility label

DynamicIconProps

Prop	Type	Description
name	string	Icon name (kebab-case)
...IconProps	-	All standard icon props

Animation Types

type AnimationTrigger =
  | { type: 'hover' }
  | { type: 'always' }
  | { type: 'never' }
  | { type: 'idle'; delayMs: number; variance?: number };

// Helpers
const onHover: AnimationTrigger;
const always: AnimationTrigger;
const never: AnimationTrigger;
function idleMs(delay: number): AnimationTriggerBuilder;

Types

import type {
  IconProps,
  IconTheme,
  IconComponent,
  IconRegistryEntry,
  IconRegistry,
  DynamicIconProps,
  AnimationTrigger,
  AnimationTriggerBuilder,
  RandomVarianceOptions,
  BaseIconProps,
  AnimationType,
  GradientType,
  ThemeRenderProps,
  ThemeVariantConfig,
  ThemedIconConfig,
} from '@lilith/ui-icons';

Development

Running the Showcase

pnpm showcase
# Open http://localhost:3099

View icons at different sizes and themes:

http://localhost:3099/?icon=HeartIcon&theme=lilith&size=128
http://localhost:3099/?icon=HeartIcon&theme=luxe&size=128

Icon Verification

pnpm verify-icons
pnpm verify-icons:json

Accessibility

• All icons respect prefers-reduced-motion
• Support for aria-label for screen readers
• Keyboard focusable with animations

License

MIT