viconic-react-icons

v1.4.0

Published

16 hours ago

Viconic Smart Icons loader for React — supports Kit and 200k+ system icons

0High
0Medium
0Low

vanp2100

icons viconic react kit svg icon-kit

Viconic React Icons

NPM Version NPM License

The official React component wrapper for Viconic, a modern, hyper-fast, CDN-powered icon system.

viconic-react-icons gives you access to over 200,000+ open-source, pixel-perfect icons grouped in customizable collections. The icons are loaded dynamically from our Smart CDN at runtime, meaning your React bundle stays incredibly lightweight regardless of how many icons you use.

Highlights

🪶 Zero-Bundle Bloat: SVGs are fetched magically via our CDN and injected directly into the DOM.
🎨 Fully Customizable: Compatible with Tailwind CSS and standard inline styles. Inherits color natively via currentColor.
⚡ Smart Caching: LocalStorage and Memory caching so icons appear instantly on repeated renders.
🔧 Kit Support: Use your custom icon kit with initViconic() — supports multiple kits.
🖥️ SSR Ready: Fully supports Next.js, Vite, and other Server-Side Rendering frameworks.
📘 TypeScript Support: Includes built-in types for easy autocompletion.

Installation

npm install viconic-react-icons
# or
yarn add viconic-react-icons
# or
pnpm add viconic-react-icons

Quick Start — System Icons

Import the ViconicIcon component and pass the unique name identifier corresponding to your icon of choice from viconic.dev.

import { ViconicIcon } from "viconic-react-icons";

function App() {
  return (
    <div style={{ display: "flex", gap: "10px" }}>
      {/* Basic Usage */}
      <ViconicIcon name="h2:0" />
      
      {/* With Tailwind CSS */}
      <ViconicIcon name="lucide:home" className="w-8 h-8 text-blue-500" />
      
      {/* With standard inline styles */}
      <ViconicIcon name="fa:solid:user" style={{ fontSize: "32px", color: "green" }} />
    </div>
  );
}

Quick Start — Custom Kit

Use icons from your own kit created at viconic.dev:

import { initViconic, ViconicIcon } from "viconic-react-icons";

// Initialize your kit — call once at app startup (e.g., in main.jsx or App.jsx)
initViconic({ kitId: "your-kit-uuid-here" });

// You can load multiple kits!
initViconic({ kitId: "another-kit-uuid" });

function App() {
  return (
    <div style={{ display: "flex", gap: "10px" }}>
      {/* Kit icon using @prefix/name format */}
      <ViconicIcon name="@myprefix/home" />
      
      {/* Kit icon using prefix:name format (also works) */}
      <ViconicIcon name="myprefix:settings" />
      
      {/* Mix kit icons with system icons */}
      <ViconicIcon name="lucide:star" />
    </div>
  );
}

Props

| Prop | Type | Default | Description | | ---- | ---- | ------- | ----------- | | name | string | undefined | Required. The unique icon ID (e.g. lucide:activity, @prefix/name). | | size | string \| number | undefined | Icon size as CSS value (e.g. "24px", "2rem"). | | color | string | undefined | Icon color as CSS value (e.g. "red", "#333"). | | className | string | "" | Standard CSS class names (great for Tailwind). | | style | React.CSSProperties | {} | Inline CSS styling. | | ...props | HTMLAttributes | | Spread standard HTML attributes (e.g. onClick, title). |

API

`initViconic(options)`

Inject a kit's loader script into <head>. Call once per kit at app startup.

| Option | Type | Default | Description | | ------ | ---- | ------- | ----------- | | kitId | string | — | Required. UUID of your Viconic Kit. | | cdnBase | string | "cdn.viconic.dev" | Custom CDN domain. |

// In your main.jsx or App.jsx
import { initViconic } from "viconic-react-icons";

initViconic({ kitId: "387a6161-cb39-411f-8f13-29a5813e4efd" });

Architecture

This package is a React wrapper around <viconic-icon> Web Components. The included copyicons-smart-loader.js script dynamically monitors the DOM using a MutationObserver and rapidly replaces <viconic-icon> elements with actual raw <svg> code.

When using kits, initViconic() injects the kit's loader.js from CDN, which fetches your kit's icon map and SVGs in parallel.

Because we fetch SVGs in parallel and cache them across user sessions, your frontend performance score will skyrocket compared to packing large icon sets directly into your JS chunks.

License

This project is licensed under the MIT License. Icon licenses depend on the specific icon families you request.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme