@iseer/icons

v1.2.5

Published

13 hours ago

A versatile, tree-shakable React icon library with 5,000+ icons in 12 distinct styles — solid, regular, bold, thin, and duotone across rounded, straight, and chubby corners.

0High
0Medium
0Low

inanxr

icons react svg icon-library tree-shaking iseer ui design-system duotone solid rounded accessible

✨ @iseer/icons

A hyper-versatile, tree-shakable React icon library.

5,000+ unique icons across 12 distinct styles. Solid, Regular, Bold, Thin, and Duotone — across Rounded, Straight, and Chubby corners. Built for modern React.

🚀 Why `@iseer/icons`?

| Feature | Details | | :--- | :--- | | ✂️ 100% Tree-Shakable | Barrel-file ESM architecture. You only bundle what you import — even from 50,000+ icon instances. | | 🎨 12 Styles per Icon | 5 weights (Solid, Regular, Bold, Thin, Duotone) × 3 corner styles (Rounded, Straight, Chubby). | | ⚡ Optimized at Build-Time | Every SVG is parsed through an AST pipeline and minified via SVGO. Average icon: < 1KB. | | 🌍 CSS Variables | Every icon hooks into --iseer-icon-color for painless global theming. | | ♿ Accessible by Default | aria-hidden="true" on decorative icons, semantic <title> injection when you need it, perfectly respects custom aria- props. | | 🚀 Next.js RSC Ready | Zero hooks, zero context. 100% React Server Component compatible out of the box. | | 📝 Visual TypeScript | Complete type declarations with inline JSDoc Base64 Visual Previews. Hover over any icon in VS Code to see it! |

📦 Installation

npm install @iseer/icons

Other package managers:

yarn add @iseer/icons
# or
pnpm add @iseer/icons
# or
bun add @iseer/icons

Peer Dependency: react >= 16.8.0 (hooks support required).

💻 Quick Start

Import from a style subpath to ensure optimal tree-shaking:

import { Home, ArrowRight, User } from '@iseer/icons/solid-rounded';

export default function App() {
  return (
    <div style={{ display: 'flex', gap: 16 }}>
      {/* Defaults to 24px, inherits currentColor */}
      <Home />

      {/* Custom size and color */}
      <ArrowRight size={32} color="#6366f1" />

      {/* Accessible: screen readers will announce "View profile" */}
      <User size={28} title="View profile" />
    </div>
  );
}

Tip: The bare import @iseer/icons defaults to the solid-rounded style.

🎨 The 12 Styles

Every icon is available in up to 12 style variants. Mix and match weights and corner radii to match your brand.

Rounded

Straight

Chubby & Duotone

Note: The default import (import { Home } from '@iseer/icons') resolves to solid-rounded.

🎛️ Component API (Props)

Every icon accepts all standard React.SVGProps<SVGSVGElement> plus:

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | size | number \| string | 24px | Sets both width and height. Accepts px, em, rem, etc. Falls back to --iseer-icon-size. | | color | string | currentColor | Primary fill color. Falls back to --iseer-icon-color CSS var. | | secondaryColor | string | — | Fill for the secondary layer (duotone icons only). | | secondaryOpacity | number \| string | — | Opacity for the secondary layer (duotone icons only). | | title | string | — | Injects <title> for a11y and removes aria-hidden. | | className | string | — | Appended to base classes iseer-icon iseer-icon-{Name}. | | ref | Ref<SVGSVGElement> | — | Standard forwardRef. Works with Framer Motion, etc. |

All other props (e.g. onClick, data-testid, style) are passed through to the underlying <svg>.

🌈 Advanced Usage

1. Theming via CSS Variables

Forget heavy React Context providers. Every icon checks --iseer-icon-size and --iseer-icon-color before falling back to defaults, ensuring perfect React Server Component compatibility while allowing global themes!

:root {
  --iseer-icon-size: 24px;
  --iseer-icon-color: #64748b; /* Slate 500 */
}

.danger-zone {
  --iseer-icon-size: 32px;
  --iseer-icon-color: #ef4444; /* Red 500 — all icons inside inherit this */
}

2. Duotone Colors

Duotone icons have two SVG layers. Control them independently:

import { Star } from '@iseer/icons/duotone-chubby';

<Star
  color="#FBBF24"          // Primary layer: gold
  secondaryColor="#EA580C" // Secondary layer: orange
  secondaryOpacity={0.4}   // Dim the secondary layer
  size={48}
/>

3. Dynamic Import (Opt-In Multi-Style)

Need to switch an icon's style at runtime? (e.g. in a CMS, design tool, or hover effect):

import { Camera } from '@iseer/icons/dynamic';

function RuntimeIcon({ isHovered }) {
  return (
    <Camera
      weight={isHovered ? 'solid' : 'thin'}
      corner="rounded"
      size={32}
    />
  );
}

⚠️ Bundle size warning: Dynamic imports include path data for all available styles of that icon. Use static subpaths when you don't need runtime switching.

🔍 Search API

If you need to programmatically search for icons (e.g. for a CMS plugin, design tool, or dynamic picker), @iseer/icons provides a blazing-fast, globally distributed fuzzy search API powered by Cloudflare Workers.

Base URL: https://iseer-icons-api.inan-5ae.workers.dev

Fuzzy Search

Search for icons by name or slug. Supports typo tolerance.

GET /search?q=arrow&limit=5

Example Response:

{
  "query": "arrow",
  "count": 5,
  "totalMatches": 142,
  "results": [
    {
      "name": "ArrowRight",
      "slug": "arrow-right",
      "styles": [
        "bold-rounded",
        "regular-rounded",
        "solid-rounded"
      ],
      "score": 0.01
    }
  ]
}

Exact Lookup

Get details for a specific icon component.

GET /icon/ArrowRight

Example Response:

{
  "name": "ArrowRight",
  "slug": "arrow-right",
  "styles": [
    "bold-rounded",
    "regular-rounded",
    "solid-rounded"
  ]
}

♿ Accessibility (a11y)

// Decorative — screen readers ignore:
<Search />

// Meaningful — screen readers announce "Search database":
<Search title="Search database" />

🏗️ Framework Integrations

Next.js (Pages & App Router)

Works out of the box. Icons are pure SVG renderers — fully SSR and RSC compatible.

Framer Motion

Every icon uses forwardRef, so wrapping in motion() is instant:

import { motion } from 'framer-motion';
import { Spinner } from '@iseer/icons/regular-rounded';

const MotionSpinner = motion(Spinner);

<MotionSpinner
  animate={{ rotate: 360 }}
  transition={{ repeat: Infinity, duration: 1, ease: 'linear' }}
/>

Radix UI / Headless UI

Icons work as drop-in children for any component that accepts React.ReactNode.

📘 TypeScript

Full type declarations are included. Import the types directly if needed:

import type { IseerProps, IseerIcon, DynamicIseerProps } from '@iseer/icons/types';

IseerProps — Props accepted by every static icon component. DynamicIseerProps — Extends IseerProps with weight and corner for dynamic icons. IseerIcon — The component type itself (React.ForwardRefExoticComponent<...>).

❓ FAQ

How do I find the name of an icon? Icon names are PascalCased versions of their source filenames. For example, arrow-right.svg becomes ArrowRight.

You can also inspect the metadata manifest programmatically:

import manifest from '@iseer/icons/metadata';
console.log(Object.keys(manifest.icons)); // ['Home', 'User', 'ArrowRight', ...]

Why are some styles missing certain icons? Not all source assets are available in every weight/corner combination. The duotone-chubby style, for example, currently ships ~326 icons. The regular-rounded and bold-straight styles have 5,000+. If an icon is missing from a style, it simply won't be exported from that subpath.

Can I use this without React? Not directly. The components are React components that render SVG. If you need raw SVG strings or a framework-agnostic solution, you'd need to extract the path data from the metadata manifest.

Is the dynamic import tree-shakable? Yes — each icon in @iseer/icons/dynamic is individually tree-shakable. However, each icon you import will include path data for all its available styles (up to 12). Use static subpaths when you only need one style.

📜 License

Licensed under the GNU General Public License v3.0 (GPL-3.0-or-later).