icondev

Official Icon.dev SDK for React, Vue, Angular and vanilla JavaScript.

Features

• CDN-Based - Load icons on-demand from Cloudflare CDN
• Framework Support - React, Vue, Angular, Svelte, and vanilla JS
• Customizable - Size, color, stroke, and CSS classes
• Type-Safe - Full TypeScript support with auto-generated icon names
• Lightweight - Minimal bundle size with tree-shaking support
• Smart Caching - In-memory caching for optimal performance
• Simple Setup - Single config file (icondev.json)

Installation

npm install icondev

Quick Start

1. Initialize

Run the interactive setup wizard:

npx icondev init

You'll be asked for:

• Your Icon.dev API key (starts with pk_)

This creates an icondev.json file with your configuration and available icons.

2. Use in Your App

React

import { Icon } from 'icondev/react'

function App() {
  return (
    <div>
      <Icon name="arrow-right" size={24} />
      <Icon name="star" color="gold" className="my-icon" />
      <Icon name="heart" size={32} stroke="red" />
    </div>
  )
}

Vue 3

<script setup>
import { Icon } from 'icondev/vue'
</script>

<template>
  <div>
    <Icon name="arrow-right" :size="24" />
    <Icon name="star" color="gold" class="my-icon" />
    <Icon name="heart" :size="32" stroke="red" />
  </div>
</template>

Next.js

'use client'

import { Icon } from 'icondev/react'

export default function Home() {
  return <Icon name="arrow-right" size={24} />
}

API Reference

React Component

<Icon
  name="icon-slug"        // Required: Icon name from your project
  size={24}               // Optional: Size in pixels or CSS value (default: 24)
  color="currentColor"    // Optional: Fill color
  stroke="currentColor"   // Optional: Stroke color
  className="my-class"    // Optional: CSS classes
  style={{ margin: 10 }}  // Optional: Inline styles
  onLoad={() => {}}       // Optional: Called when icon loads
  onError={(err) => {}}   // Optional: Called on error
/>

React Hook

import { useIcon } from 'icondev/react'

function MyComponent() {
  const { svg, loading, error } = useIcon('arrow-right')

  if (loading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return <div dangerouslySetInnerHTML={{ __html: svg }} />
}

Vue Component

<Icon
  name="icon-slug"
  :size="24"
  color="currentColor"
  stroke="currentColor"
  class="my-class"
  @load="handleLoad"
  @error="handleError"
/>

Vue Composable

<script setup>
import { useIcon } from 'icondev/vue'

const { svg, loading, error } = useIcon('arrow-right')
</script>

<template>
  <div v-if="loading">Loading...</div>
  <div v-else-if="error">Error: {{ error.message }}</div>
  <div v-else v-html="svg" />
</template>

Core API

import {
  loadIcon,
  preloadIcons,
  getAvailableIcons,
  hasIcon,
} from 'icondev'

// Load single icon
const { svg } = await loadIcon({ name: 'arrow-right' })

// Preload icons
await preloadIcons(['icon1', 'icon2', 'icon3'])

// Get all available icons (Node.js only)
const icons = getAvailableIcons() // ['arrow-right', 'star', ...]

// Check if icon exists (Node.js only)
if (hasIcon('arrow-right')) {
  // Icon is available
}

Configuration

Project Structure

After running npx icondev init, an icondev.json file is created in your project root:

{
  "apiKey": "pk_...",
  "projectSlug": "my-project",
  "cdnUrl": "https://cdn.icon.dev",
  "icons": [
    {
      "slug": "arrow-right",
      "url": "https://cdn.icon.dev/id-my-project/arrow-right.svg",
      "collection": "arrows"
    },
    {
      "slug": "star",
      "url": "https://cdn.icon.dev/id-my-project/star.svg",
      "collection": "misc"
    }
  ],
  "updatedAt": "2025-01-15T10:00:00Z"
}

Important:

• The icondev.json file should be committed to your repository
• In Node.js/SSR: icons are loaded from this file
• In Browser: copy icondev.json to your public/ folder so it's accessible at /icondev.json
• The API key (pk_...) is a public key and is safe to commit

icondev.json

• apiKey - Your Icon.dev public API key (pk_...)
• projectSlug - Your project identifier (auto-detected from API key)
• cdnUrl - CDN base URL (usually don't need to change)
• icons - Array of all available icons in your project
• updatedAt - Timestamp of last update

CLI Commands

npx icondev init

Interactive setup wizard. Creates icondev.json with your project configuration and fetches all available icons.

npx icondev sync

Updates icondev.json with the latest icons from your Icon.dev project. Use this command when:

• New icons have been added to your project
• Icons have been removed from your project
• Existing icons have been updated

The command will show a summary of changes:

• + N icon(s) added - New icons available
• - N icon(s) removed - Icons no longer available
• ~ N icon(s) updated - Existing icons with new versions

How It Works

CDN Mode

Icons are loaded on-demand from Cloudflare CDN:

1. User calls <Icon name="arrow-right" />
2. Loader checks memory cache → miss
3. In Node.js: Loads config from icondev.json file
4. In Browser: Loads config from /icondev.json (public folder)
5. Gets icon URL from config (includes version and hash for cache busting)
6. Fetches SVG from CDN using the full URL
7. Caches in memory for future requests
8. Renders SVG

Advantages

✅ Smallest bundle size ✅ No build step required ✅ Smart in-memory caching ✅ Works everywhere (Node.js, browser, SSR) ✅ Simple single-file configuration

TypeScript

Full TypeScript support included:

import type { IconProps } from 'icondev'

const props: IconProps = {
  name: 'arrow-right',
  size: 24,
  color: 'blue'
}

Framework-Specific Notes

React

• Supports React 16.8+ (Hooks)
• Works with Next.js (use 'use client' directive)
• Works with Remix, Gatsby, Vite, etc.
• Browser setup: Copy icondev.json to your public/ folder

Vue

• Vue 3 only (uses Composition API)
• Works with Nuxt 3, Vite
• Browser setup: Copy icondev.json to your public/ folder
• For Vue 2, use core API with custom wrapper

Next.js

Use client components and ensure icondev.json is in your public/ folder:

'use client'

import { Icon } from 'icondev/react'

export default function MyComponent() {
  return <Icon name="arrow-right" />
}

Setup for Next.js:

1. Run npx icondev init in your project root
2. Copy icondev.json to public/icondev.json
3. Import and use icons in client components

Caching

• Memory cache - Loaded icons cached in memory for instant re-renders
• No disk cache - Icons loaded fresh from CDN (cached by browser/CDN)
• Browser caching - CDN responses cached by browser for offline support

Error Handling

Icons handle errors gracefully:

<Icon
  name="invalid-icon"
  onError={(error) => {
    console.error('Failed to load icon:', error)
  }}
/>

Error states get icon-error class and data-icon-error attribute.

Performance

• Bundle size: ~5KB gzipped (core) + ~2KB per adapter
• CDN: Cached globally on Cloudflare Edge
• Load time: ~20ms average (CDN mode)
• Memory usage: Minimal (icons cached as strings)

Updating Icons

To update your icon list when new icons are added to your project:

npx icondev sync

This will refresh your icondev.json with the latest icons from your Icon.dev project and show a summary of changes.

License

MIT

Support

• Email: [email protected]
• Docs: https://icon.dev/docs