@nice2dev/icons

Beautiful, lightweight, multi-color SVG icon library for React with 65+ CSS animations, four rendering variants, gradient fills, and a built-in icon picker component.

Table of Contents

• Features
• Installation
• Quick Start
• API Reference
  • Icon Component Props (NtdIconProps)
  • Size Presets (IconSize)
  • Variants (IconVariant)
  • Colors & Opacity
  • Animations (IconAnimation)
  • Gradient Fills
  • Accessibility
• NiceIconPicker
  • IconPickerEntry
  • NiceIconPickerProps
  • NiceIconPickerHandle (imperative ref)
• Creating Custom Icons (createIcon)
  • CreateIconOptions
  • IconPathRenderer
  • IconRenderProps
• Full Icon Catalog
• Full Animation Catalog
• CSS Theming Variables
• Tree Shaking
• Storybook
• Build & Development
• License

Features

• 300+ icons across 17 categories (navigation, actions, UI, media, files, fun, weather, shapes, business, social, devtech, health, brand, brand-studio, brand-lockup, brand-enterprise)
• 4 variants per icon — solid, outline, duotone, flat (badge-style)
• Multi-color — primaryColor, secondaryColor, accentColor with per-channel opacity
• Gradient fills — 12 built-in presets (sunset, ocean, aurora…), linear/radial, animated
• 65+ CSS animations — spin, pulse, bounce, heartbeat, glitch, neon, explode, and many more
• Tree-shakeable — import only what you need; unused icons are eliminated at build time
• NiceIconPicker — searchable, categorized dropdown component for icon selection
• createIcon() factory — build your own icons following the same API
• Zero runtime dependencies — only react and react-dom as peer deps
• Full TypeScript — strict types, IntelliSense, TSDoc on every export
• Accessible — role, aria-hidden, aria-label, <title> support
• CSS variable theming — customize the picker with CSS custom properties

Installation

npm install @nice2dev/icons

Peer dependencies: react >= 17.0.0, react-dom >= 17.0.0.

Quick Start

import { NtdHome, NtdSearch, NtdHeart } from '@nice2dev/icons';

function App() {
  return (
    <>
      {/* Solid blue home icon, large */}
      <NtdHome size="lg" primaryColor="#3b82f6" />

      {/* Animated search icon */}
      <NtdSearch size="md" animation="pulse" />

      {/* Duotone heart with custom colors */}
      <NtdHeart
        variant="duotone"
        primaryColor="#e74c3c"
        secondaryColor="#fca5a5"
        animation="heartbeat"
      />
    </>
  );
}

API Reference

Icon Component Props (NtdIconProps)

Every icon component accepts these props (extends SVGProps<SVGSVGElement>):

| Prop | Type | Default | Description | |------|------|---------|-------------| | size | IconSize | 'md' | Named preset or pixel number | | variant | IconVariant | 'solid' | Rendering variant | | primaryColor | string | 'currentColor' | Main icon color | | secondaryColor | string | primaryColor | Secondary color (duotone background) | | accentColor | string | '#ffffff' | Accent color for detail elements | | primaryOpacity | number | 1 | Opacity of primary elements (0–1) | | secondaryOpacity | number | 0.4 | Opacity of secondary elements (0–1) | | accentOpacity | number | 1 | Opacity of accent elements (0–1) | | strokeWidth | number | 2 | Base stroke width for outline/duotone | | strokeLinecap | 'round' \| 'square' \| 'butt' | 'round' | Stroke line cap style | | strokeLinejoin | 'round' \| 'miter' \| 'bevel' | 'round' | Stroke line join style | | animation | IconAnimation | undefined | CSS animation name | | animationDuration | string | CSS default | Duration override (e.g. '0.5s') | | gradient | GradientPreset | undefined | Apply a gradient fill preset | | gradientType | 'linear' \| 'radial' | 'linear' | Gradient shape | | gradientAngle | number | 135 | Angle for linear gradients (degrees) | | gradientAnimation | 'shift' \| 'spin' \| 'pulse' | undefined | Animate the gradient | | title | string | undefined | Accessible title for screen readers | | className | string | undefined | Custom CSS class | | style | CSSProperties | undefined | Inline styles | | ref | Ref<SVGSVGElement> | — | Forward ref to the <svg> element |

Plus all standard SVGProps<SVGSVGElement> attributes (onClick, id, data-*, etc.).

Size Presets (IconSize)

type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'xxl' | 'xxxl' | number;

| Preset | Pixels | |--------|--------| | xs | 12 | | sm | 16 | | md | 24 | | lg | 32 | | xl | 48 | | 2xl | 64 | | xxl | 96 | | xxxl | 128 |

Pass a number for a custom pixel size: <NtdStar size={20} />.

The pixel map is exported as SIZE_MAP: Record<string, number>.

Variants (IconVariant)

type IconVariant = 'solid' | 'outline' | 'duotone' | 'flat';

| Variant | Description | |---------|-------------| | solid | Filled shapes using fill | | outline | Stroked paths with fill="none" | | duotone | Background shape at secondaryOpacity + foreground stroke | | flat | Colored badge background (secondaryColor, rounded rect) with solid content on top |

<NtdHome variant="outline" primaryColor="#000" strokeWidth={1.5} />

Colors & Opacity

<NtdHeart
  variant="duotone"
  primaryColor="#e74c3c"      // foreground stroke
  secondaryColor="#fca5a5"    // background fill
  secondaryOpacity={0.3}      // background opacity
  accentColor="#fff"           // small details
/>

• If secondaryColor is omitted, it defaults to primaryColor.
• If accentColor is omitted, it defaults to '#ffffff'.

Animations (IconAnimation)

Apply an animation by name:

<NtdBell animation="shake" />
<NtdBell animation="shake" animationDuration="0.3s" />

Each animation maps to a CSS class .ntd-anim-{name} defined in animations.css (auto-imported).

See Full Animation Catalog for the complete list.

Gradient Fills

Apply gradient fills using the gradient prop with one of 12 built-in presets:

<NtdHeart gradient="sunset" />
<NtdStar gradient="ocean" gradientType="radial" />
<NtdZap gradient="neon" gradientAnimation="spin" />
<NtdGlobe gradient="aurora" gradientAngle={45} />

Available Presets (GradientPreset)

| Preset | Colors | |--------|--------| | sunset | #ff6b6b → #feca57 → #ff9ff3 | | ocean | #0652DD → #1B9CFC → #38ada9 | | forest | #0a3d0a → #1e8449 → #58D68D | | fire | #e74c3c → #f39c12 → #f1c40f | | ice | #74b9ff → #a29bfe → #dfe6e9 | | neon | #6c5ce7 → #fd79a8 → #00cec9 | | gold | #f9ca24 → #f0932b → #e17055 | | purple-haze | #6c5ce7 → #a55eea → #e056a0 | | aurora | #00b894 → #00cec9 → #0984e3 → #6c5ce7 | | midnight | #0c0c1d → #1e3a5f → #2c3e50 | | candy | #ff6b81 → #ffa502 → #2ed573 | | steel | #636e72 → #b2bec3 → #dfe6e9 |

Color stops are exported as GRADIENT_PRESETS: Record<GradientPreset, readonly string[]>.

Gradient Animations (GradientAnimation)

| Animation | Effect | |-----------|--------| | shift | Slides gradient colors horizontally | | spin | Rotates the gradient around the icon center | | pulse | Pulsates between stop colors |

Animations use SVG SMIL (<animate> / <animateTransform>) — no JavaScript runtime, works in all modern browsers.

Accessibility

• When title is provided → role="img", aria-label={title}, <title> element inside SVG
• When title is omitted → aria-hidden="true", role="presentation" (decorative)

<NtdSearch title="Search" />        {/* accessible */}
<NtdStar />                         {/* decorative, hidden from AT */}

NiceIconPicker

A fully-featured, searchable, categorized icon picker dropdown.

import { NiceIconPicker, type IconPickerEntry } from '@nice2dev/icons';
import { NtdHome, NtdSearch, NtdHeart } from '@nice2dev/icons';

const icons: IconPickerEntry[] = [
  { name: 'NtdHome',   Component: NtdHome,   category: 'UI' },
  { name: 'NtdSearch', Component: NtdSearch,  category: 'Actions' },
  { name: 'NtdHeart',  Component: NtdHeart,   category: 'UI' },
];

function App() {
  const [selected, setSelected] = useState<string | null>(null);

  return (
    <NiceIconPicker
      icons={icons}
      value={selected}
      onChange={(name) => setSelected(name)}
      variant="solid"
      placeholder="Pick an icon…"
      clearable
    />
  );
}

IconPickerEntry

interface IconPickerEntry {
  name: string;                              // unique identifier (e.g. 'NtdHome')
  Component: ForwardRefExoticComponent<…>;   // the icon component
  category: string;                          // grouping label
}

NiceIconPickerProps

| Prop | Type | Default | Description | |------|------|---------|-------------| | icons | IconPickerEntry[] | required | Full icon registry | | value | string \| null | null | Currently selected icon name | | onChange | (name: string \| null, entry: IconPickerEntry \| null) => void | — | Selection callback | | placeholder | string | 'Select icon…' | Placeholder text | | variant | IconVariant | 'solid' | Variant for grid preview | | gridIconSize | IconSize \| number | 'md' | Icon size in the grid | | triggerIconSize | IconSize \| number | 'sm' | Icon size in trigger button | | categories | string[] | auto-detected | Ordered category tab names | | className | string | — | Additional CSS class | | disabled | boolean | false | Disable the picker | | clearable | boolean | true | Show "Clear selection" button |

NiceIconPickerHandle (imperative ref)

const ref = useRef<NiceIconPickerHandle>(null);
ref.current?.open();   // programmatically open
ref.current?.close();  // programmatically close
ref.current?.toggle(); // toggle open/closed

interface NiceIconPickerHandle {
  open: () => void;
  close: () => void;
  toggle: () => void;
}

Creating Custom Icons (createIcon)

Build icons following the same pattern as the built-in library:

import { createIcon } from '@nice2dev/icons';

export const NtdMyIcon = createIcon({
  displayName: 'NtdMyIcon',
  viewBox: '0 0 24 24',   // optional, defaults to '0 0 24 24'
  paths: {
    solid: ({ primaryColor }) => (
      <path d="M12 2l10 20H2z" fill={primaryColor} />
    ),
    outline: ({ primaryColor, strokeWidth }) => (
      <path d="M12 2l10 20H2z" stroke={primaryColor} strokeWidth={strokeWidth} fill="none" />
    ),
    duotone: ({ primaryColor, secondaryColor, secondaryOpacity, strokeWidth }) => (
      <>
        <path d="M12 2l10 20H2z" fill={secondaryColor} opacity={secondaryOpacity} />
        <path d="M12 2l10 20H2z" stroke={primaryColor} strokeWidth={strokeWidth} fill="none" />
      </>
    ),
    flat: ({ primaryColor, secondaryColor }) => (
      <>
        <rect x="2" y="2" width="20" height="20" rx="4" fill={secondaryColor} />
        <path d="M12 2l10 20H2z" fill={primaryColor} />
      </>
    ),
  },
});

// Usage — exactly like any built-in icon:
<NtdMyIcon size="lg" variant="duotone" primaryColor="#8b5cf6" animation="pulse" />

CreateIconOptions

| Field | Type | Default | Description | |-------|------|---------|-------------| | displayName | string | required | React display name | | viewBox | string | '0 0 24 24' | SVG viewBox | | paths.solid | IconPathRenderer | required | Solid variant renderer | | paths.outline | IconPathRenderer | required | Outline variant renderer | | paths.duotone | IconPathRenderer | required | Duotone variant renderer | | paths.flat | IconPathRenderer | required | Flat (badge) variant renderer |

IconPathRenderer

type IconPathRenderer = (props: IconRenderProps) => React.ReactNode;

IconRenderProps

Properties passed to every path renderer (pre-resolved from user props):

| Prop | Type | Description | |------|------|-------------| | variant | IconVariant | Active variant | | primaryColor | string | Resolved primary color | | secondaryColor | string | Resolved secondary color | | accentColor | string | Resolved accent color | | primaryOpacity | number | Primary opacity | | secondaryOpacity | number | Secondary opacity | | accentOpacity | number | Accent opacity | | strokeWidth | number | Stroke width | | strokeLinecap | 'round' \| 'square' \| 'butt' | Stroke line cap | | strokeLinejoin | 'round' \| 'miter' \| 'bevel' | Stroke line join |

Full Icon Catalog

Navigation (14 icons)

NtdArrowUp · NtdArrowDown · NtdArrowLeft · NtdArrowRight · NtdChevronUp · NtdChevronDown · NtdChevronLeft · NtdChevronRight · NtdMenu · NtdClose · NtdMoreHorizontal · NtdMoreVertical · NtdExternalLink · NtdRefresh

Actions (25 icons)

NtdSearch · NtdEdit · NtdTrash · NtdSave · NtdDownload · NtdUpload · NtdShare · NtdCopy · NtdClipboard · NtdPlus · NtdMinus · NtdCheck · NtdFilter · NtdSort · NtdPrint · NtdZoomIn · NtdZoomOut · NtdUndo · NtdRedo · NtdLink · NtdSettings · NtdLogIn · NtdLogOut · NtdLock · NtdUnlock

UI & Status (26 icons)

NtdHome · NtdUser · NtdUsers · NtdHeart · NtdStar · NtdBell · NtdEye · NtdEyeOff · NtdInfo · NtdWarning · NtdError · NtdSuccess · NtdHelp · NtdClock · NtdCalendar · NtdTag · NtdBookmark · NtdFlag · NtdThumbUp · NtdThumbDown · NtdShield · NtdGlobe · NtdMap · NtdPin · NtdSun · NtdMoon

Media & Communication (19 icons)

NtdPlay · NtdPause · NtdStop · NtdSkipForward · NtdSkipBack · NtdVolume · NtdVolumeMute · NtdImage · NtdCamera · NtdVideo · NtdMicrophone · NtdMusic · NtdMail · NtdPhone · NtdChat · NtdSend · NtdNotification · NtdWifi · NtdBluetooth

Files & Misc (31 icons)

NtdFile · NtdFileText · NtdFolder · NtdFolderOpen · NtdArchive · NtdDatabase · NtdCloud · NtdCloudUpload · NtdCloudDownload · NtdTerminal · NtdCode · NtdGit · NtdPackage · NtdLayers · NtdGrid · NtdList · NtdTable · NtdSmartphone · NtdMonitor · NtdCpu · NtdZap · NtdKey · NtdAward · NtdCoffee · NtdCart · NtdCreditCard · NtdPieChart · NtdBarChart · NtdActivity · NtdTarget · NtdTruck

Fun & Emoji (13 icons)

NtdDumpsterFire · NtdRocket · NtdGamepad · NtdPuzzle · NtdPartyPopper · NtdTrophy · NtdCrown · NtdDice · NtdSmiley · NtdSad · NtdSkull · NtdGhost · NtdLightning

Weather & Nature (20 icons)

NtdSunrise · NtdSunset · NtdRain · NtdSnow · NtdThunderstorm · NtdWind · NtdDroplet · NtdThermometer · NtdUmbrella · NtdLeaf · NtdFlower · NtdTree · NtdMountain · NtdWave · NtdFire · NtdSnowflake · NtdCompass · NtdAnchor · NtdFeather · NtdBug

Arrows & Shapes (22 icons)

NtdArrowUpCircle · NtdArrowDownCircle · NtdArrowLeftCircle · NtdArrowRightCircle · NtdSquare · NtdCircle · NtdTriangle · NtdHexagon · NtdOctagon · NtdDiamond · NtdPentagon · NtdCross · NtdStar4 · NtdCornerUpLeft · NtdCornerUpRight · NtdCornerDownLeft · NtdCornerDownRight · NtdMaximize · NtdMinimize · NtdMove · NtdRepeat · NtdShuffle

Business & Finance (16 icons)

NtdBriefcase · NtdDollar · NtdWallet · NtdReceipt · NtdBank · NtdTrendUp · NtdTrendDown · NtdPercent · NtdInvoice · NtdStore · NtdBarcode · NtdCalculator · NtdPresentation · NtdClipboardCheck · NtdPiggyBank · NtdCoins

Social & Communication (8 icons)

NtdAtSign · NtdPhoneOff · NtdBubble · NtdThumbsUp · NtdThumbsDown · NtdBellRing · NtdMegaphone · NtdQrCode

Dev & Tech (9 icons)

NtdBrackets · NtdServer · NtdGitBranch · NtdGitCommit · NtdGitMerge · NtdBattery · NtdSlash · NtdHash · NtdBugDev

Food & Health (13 icons)

NtdApple · NtdPizza · NtdGlass · NtdHeartPulse · NtdPill · NtdSyringe · NtdStethoscope · NtdWeight · NtdBandaid · NtdCake · NtdEgg · NtdHamburger · NtdDna

Brand & Logo (14 icons)

NtdNiceToDev · NtdNiceMonogram · NtdNiceOrbit · NtdNiceSpark · NtdNiceShield · NtdNiceBadge · NtdNiceCore · NtdNiceCrest · NtdNiceHelix · NtdNicePortal · NtdNicePulseMark · NtdNiceFlagship · NtdOmniVerk · NtdOmniVerkLogo

Brand Studio (25 icons)

NtdStudioGrid · NtdStudioBlueprint · NtdStudioCursor · NtdStudioPrototype · NtdStudioComponent · NtdStudioToken · NtdStudioPalette · NtdStudioBrush · NtdStudioPenTool · NtdStudioLayerStack · NtdStudioSpline · NtdStudioNodes · NtdStudioFlow · NtdStudioRelease · NtdStudioRocketMark · NtdStudioAIBrain · NtdStudioNeural · NtdStudioChipmark · NtdStudioTerminalMark · NtdStudioForge · NtdStudioWireframe · NtdStudioPersona · NtdStudioBenchmark · NtdStudioStudio · NtdStudioBeacon

Brand Lockups (4 icons)

NtdNiceLockupHorizontal · NtdNiceLockupStacked · NtdNiceWordmark · NtdNiceSymbolWordmark

Brand Enterprise (18 icons)

NtdEnterpriseRoadmap · NtdEnterpriseBacklog · NtdEnterpriseKanban · NtdEnterpriseSprint · NtdEnterpriseMilestone · NtdEnterprisePipeline · NtdEnterpriseDeploy · NtdEnterpriseMonitor · NtdEnterpriseAlert · NtdEnterpriseSla · NtdEnterpriseKpi · NtdEnterpriseRevenue · NtdEnterpriseRisk · NtdEnterpriseCompliance · NtdEnterpriseGateway · NtdEnterpriseDataMesh · NtdEnterpriseFeatureFlag · NtdEnterpriseWorkspace

Full Animation Catalog

Core Transforms (13)

spin · spin-reverse · pulse · bounce · shake · float · flip · glow · wiggle · rubber · swing · tada · heartbeat

Entrance Animations (22)

fade-in · slide-up · slide-down · slide-left · slide-right · drop · rise · roll-in · materialize · vortex · meteor · scale-in · signature · draw-sequence · stroke-order · glow-trace · seal-stamp · reveal · typewriter · unfold · assemble · draw · draw-from-dot

Exit Animations (3)

scale-out · fold · dissolve

Organic / Natural (10)

breathe · drift · orbit · sway · tilt · rock · pendulum · levitate · flap · skate

Energetic / Impact (10)

jello · pop · squeeze · crush · stretch · stomp · snap · twist · dash · surge

Effects / Digital (8)

flash · blink · flicker · vibrate · tremble · glitch · neon · earthquake

Complex Transforms (7)

wobble · spiral · warp · morph · zoom-pulse · ripple · radar

Dramatic (6)

ping · implode · explode · scatter · rotate-x · draw-loop

CSS Theming Variables

Icon Picker

Override these CSS custom properties on a parent element to theme the picker:

.my-theme {
  --ntd-picker-bg: #1a1a2e;
  --ntd-picker-border: #333;
  --ntd-picker-text: #e0e0e0;
  --ntd-picker-accent: #6366f1;
  --ntd-picker-hover: rgba(99, 102, 241, 0.15);
  --ntd-picker-radius: 8px;
}

Animation Classes

All animation classes follow the pattern .ntd-anim-{name}. You can override timing in CSS:

.ntd-anim-spin {
  animation-duration: 0.5s !important;
}

Or use the animationDuration prop inline:

<NtdBell animation="spin" animationDuration="0.5s" />

Tree Shaking

The library uses sideEffects: ["*.css"] in package.json and preserveModules in Rollup, so bundlers like webpack and vite can eliminate unused icons at build time.

// Only NtdHome and NtdSearch (+ CSS) end up in your bundle
import { NtdHome, NtdSearch } from '@nice2dev/icons';

Storybook

Run the interactive component explorer:

npm run storybook        # dev server on http://localhost:6006
npm run build-storybook  # static build to storybook-static/

Stories cover:

• Components/Icon — all props, variants, sizes, colors, animations
• Components/NiceIconPicker — controlled picker, disabled, outline variant
• Components/Animations — full gallery of 65+ animations
• Guides/createIcon — building custom icons with the factory

Build & Development

npm install              # install dependencies
npm run build            # tsc (types) + rollup (CJS + ESM)
npm run dev              # rollup watch mode
npm run demo             # vite dev server for the demo app
npm run demo:build       # build the demo
npm run lint             # eslint
npm run storybook        # storybook dev
npm run build-storybook  # build storybook

Output Structure

dist/
  cjs/          # CommonJS modules
  esm/          # ES modules
  types/        # TypeScript declarations (.d.ts)

Entry points in package.json:

• main → dist/cjs/index.js
• module → dist/esm/index.js
• types → dist/types/index.d.ts

React Server Components (RSC)

Use icons in Server Components without "use client":

// In a Server Component (app/page.tsx)
import { createIconRSC } from '@nice2dev/icons/rsc';

// Create RSC-compatible icon
const HomeIcon = createIconRSC({
  displayName: 'HomeIcon',
  paths: { /* ... */ }
});

export default function Page() {
  return <HomeIcon size="md" primaryColor="#3b82f6" />;
}

RSC vs Client Exports

| Import Path | Use Case | |-------------|----------| | @nice2dev/icons | Standard usage (includes animations, color scheme detection) | | @nice2dev/icons/rsc | Server Components (no hooks, streaming-friendly) | | @nice2dev/icons/client | Client-only features ("use client" directive) |

RSC Utilities

import { renderIconToString, isRSCIcon, wrapAsRSC } from '@nice2dev/icons/rsc';

// Render to SVG string (for SSR/email)
const svgString = renderIconToString(MyIcon, { size: 'lg' });

// Check if icon is RSC-compatible
isRSCIcon(MyIcon); // true/false

// Wrap existing icon for RSC
const MyIconRSC = wrapAsRSC(MyIcon);

Design Tokens

Generate Style Dictionary compatible design tokens for your design system:

import {
  generateIconTokens,
  generateCSSVariables,
  generateTailwindConfig,
  toFigmaTokens,
} from '@nice2dev/icons/design-tokens';

// Generate tokens with custom configuration
const tokens = generateIconTokens({
  prefix: 'myapp',
  namespace: 'icon',
  colorTokens: {
    primary: '#6366f1',
    secondary: '#a5b4fc',
  },
  sizeTokens: {
    sm: '14px',
    md: '20px',
    lg: '28px',
  },
});

// Generate CSS variables
const css = generateCSSVariables(tokens);
// :root {
//   --myapp-icon-size-sm: 14px;
//   --myapp-icon-color-primary: #6366f1;
//   ...
// }

// Generate Tailwind config
const tailwindConfig = generateTailwindConfig(tokens);

// Export for Figma Tokens plugin
const figmaTokens = toFigmaTokens(tokens);

Default Token Values

| Category | Tokens | |----------|--------| | Sizes | xs (12px), sm (16px), md (24px), lg (32px), xl (48px), 2xl (64px) | | Colors | primary, secondary, accent, success, warning, error, info, muted | | Strokes | thin (1), normal (1.5), medium (2), thick (2.5), bold (3) |

Headless UI / shadcn/ui Integration

Seamless integration with Radix UI, Headless UI, and shadcn/ui:

import { NtdSettings, NtdChevronDown } from '@nice2dev/icons';
import {
  forwardRefIcon,
  createRadixIcon,
  withRadixState,
  shadcnIconClasses,
} from '@nice2dev/icons/headless-ui';

// Create ref-compatible icon for Radix asChild pattern
const SettingsIcon = forwardRefIcon(NtdSettings);

// Icon with Radix-compatible defaults
const SearchIcon = createRadixIcon(NtdSearch, {
  className: 'text-muted-foreground',
});

// State-aware icon (rotates on data-state="open")
const ChevronIcon = withRadixState(NtdChevronDown);

// Use with shadcn/ui Button
<Button>
  <SettingsIcon className={shadcnIconClasses.buttonLeft} />
  Settings
</Button>

shadcn/ui Class Presets

shadcnIconClasses = {
  button: 'h-4 w-4',
  buttonLeft: 'mr-2 h-4 w-4',
  buttonRight: 'ml-2 h-4 w-4',
  sm: 'h-3.5 w-3.5',
  lg: 'h-5 w-5',
  iconOnly: 'h-4 w-4',
  nav: 'h-4 w-4 shrink-0',
  dropdown: 'mr-2 h-4 w-4',
  spinner: 'h-4 w-4 animate-spin',
  // ...
}

Dynamic Class Generation

import { getIconClassName } from '@nice2dev/icons/headless-ui';

getIconClassName({ size: 'lg', variant: 'muted' });
// → 'h-5 w-5 text-muted-foreground'

getIconClassName({ interactive: true, spinning: true });
// → 'h-4 w-4 transition-colors hover:text-foreground cursor-pointer animate-spin'

Utilities & Hooks

Powerful utilities for advanced icon management:

import {
  useIcon,
  useReducedMotion,
  preloadIcons,
  registerIcon,
  getIconFromRegistry,
  withReducedMotionProps,
  createAccessibleIconProps,
  isIconComponent,
  isValidIconName,
  useBatchIcons
} from '@nice2dev/icons/utilities';

// Dynamic icon loading with suspense support
function DynamicIcon({ name }: { name: string }) {
  const { icon: Icon, loading, error } = useIcon(name);
  
  if (loading) return <span>Loading...</span>;
  if (error) return <span>Icon not found</span>;
  if (!Icon) return null;
  
  return <Icon className="w-6 h-6" />;
}

// Respect user's reduced motion preference
function AnimatedIcon() {
  const prefersReducedMotion = useReducedMotion();
  
  return (
    <NtdSpinner 
      className={prefersReducedMotion ? '' : 'animate-spin'} 
    />
  );
}

// Preload icons for better performance
useEffect(() => {
  preloadIcons(['NtdHome', 'NtdUser', 'NtdSettings']);
}, []);

// Icon registry for custom icons
registerIcon('MyCustomIcon', MyCustomIconComponent);
const CustomIcon = getIconFromRegistry('MyCustomIcon');

// Accessibility helpers
const a11yProps = createAccessibleIconProps('Search', true);
// → { role: 'img', 'aria-label': 'Search' }

// Type guards
if (isIconComponent(SomeComponent)) {
  // TypeScript knows it's an icon
}

// Batch loading multiple icons
const { icons, loading, errors } = useBatchIcons(['NtdHome', 'NtdUser']);

CLI Tool

Preview, list, search and export icons from the command line:

# Preview icon in browser
npx @nice2dev/icons preview NtdHome

# List all icons
npx @nice2dev/icons list

# List icons in a category
npx @nice2dev/icons list --category=ui

# Search icons
npx @nice2dev/icons search "arrow"

# Export icons
npx @nice2dev/icons export --format=svg --icons=NtdHome,NtdUser

# Show icon info
npx @nice2dev/icons info NtdHeart

License

MIT © NiceToDev