viconic-react-icons

v1.5.8

Published

2 months 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

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.
⚡ Smart Caching: LocalStorage and Memory caching so icons appear instantly on repeated renders. Event-driven icon injection for ultra-fast, progressive rendering.
�� Fully Customizable: Compatible with Tailwind CSS and standard inline styles. Inherits color natively via currentColor.
🔧 Kit Support: Use your custom icon kit with initViconic() — supports multiple kits and user-uploaded SVGs simultaneously.
🖥️ SSR Ready: Fully supports Next.js, Vite, Remix, 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

1. System Icons (200k+ Free 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>
  );
}

2. Custom Kits & Uploaded Icons

Use icons from your own customized kit (including your own SVG uploads) 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.tsx)
initViconic({ kitId: "your-kit-uuid-here" });

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

function App() {
  return (
    <div style={{ display: "flex", gap: "10px" }}>
      {/* Kit icon using @prefix/name format */}
      <ViconicIcon name="@myprefix/home" />

      {/* User uploaded icon format */}
      <ViconicIcon name="@myprefix/my-custom-logo" size="48px" />

      {/* Mix kit icons with system icons */}
      <ViconicIcon name="lucide:star" color="#FFD700" />
    </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 Reference

`initViconic(options)`

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

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

// Copy the exact snippet from the "Usage & Setup" tab in your Kit Editor
// It already includes the correct version timestamp for your kit.
initViconic({ kitId: "387a6161-cb39-411f-8f13-29a5813e4efd", version: "1774867419" });

⚠️ Important — Cache Busting:
Every time you update your kit on viconic.dev (add/remove icons, click "Update Kit"), you must update the version value in initViconic() to the new timestamp shown in the Usage & Setup tab.
This ensures your users always load the latest kit instead of a stale cached version.
The Usage & Setup tab always shows the ready-to-copy snippet with the current version pre-filled.

🧠 Architecture

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

When using kits, initViconic() injects the kit's loader from CDN, which leverages chunked batch fetching, event-driven rendering, and parallel processing.

Because we fetch SVGs in parallel and cache them heavily via LocalStorage 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 use.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme