API Reference

Core API

Import from the main package for framework-agnostic functions.

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

loadIcon()

Load a single icon programmatically.

const result = await loadIcon({ name: 'arrow-right' })
console.log(result.svg)  // → "<svg>...</svg>"

Parameters:

name (string) - Icon slug

Returns: Promise<{ svg: string }>

Example:

try {
  const { svg } = await loadIcon({ name: 'arrow-right' })
  document.getElementById('icon').innerHTML = svg
} catch (error) {
  console.error('Failed to load icon:', error)
}

preloadIcons()

Preload icons into cache for instant display.

await preloadIcons(['home', 'search', 'user'])

Parameters:

names (string[]) - Array of icon slugs

Returns: Promise<void>

Preload critical icons during app initialization for better UX.

Use cases:

Icons above the fold
Modal/dialog icons
Navigation icons

Example:

// React
useEffect(() => {
  preloadIcons(['logo', 'menu', 'close'])
}, [])

// Vue
onMounted(() => {
  preloadIcons(['logo', 'menu', 'close'])
})

getAvailableIcons()

Get list of all available icons in your project.

const icons = getAvailableIcons()
console.log(icons)  // → ['arrow-right', 'star', 'heart', ...]

Returns: string[]

Node.js only: This function reads from icondev.json and only works in Node.js environment (not in browser).

Example:

function IconPicker() {
  const icons = getAvailableIcons()

  return (
    <select>
      {icons.map(name => (
        <option key={name} value={name}>{name}</option>
      ))}
    </select>
  )
}

hasIcon()

Check if an icon exists in your project.

if (hasIcon('home')) {
  console.log('Icon exists!')
}

Parameters:

name (string) - Icon slug

Returns: boolean

Node.js only: This function reads from icondev.json and only works in Node.js environment (not in browser).

clearCache()

Clear the in-memory icon cache.

import { clearCache } from 'icondev'

clearCache()

This only clears memory cache. Icons will be re-fetched from CDN on next use.

React API

Import from icondev/react for React components and hooks.

import { Icon, useIcon, IconDevProvider } from 'icondev/react'

`<Icon>` Component

Render an icon with React.

<Icon
  name="home"
  size={24}
  color="currentColor"
  stroke="#333"
  className="hover:scale-110"
  style={{ margin: 10 }}
  onLoad={() => console.log('Loaded')}
  onError={(err) => console.error(err)}
/>

Props:

Prop	Type	Default	Description
`name`	`string`	required	Icon slug
`size`	`number \| string`	`24`	Size in pixels or CSS value
`color`	`string`	`currentColor`	Fill color
`stroke`	`string`	`currentColor`	Stroke color
`className`	`string`	`''`	CSS classes
`style`	`object`	`{}`	Inline styles
`onLoad`	`() => void`	-	Called when icon loads
`onError`	`(error: Error) => void`	-	Called on error

Example:

import { Icon } from 'icondev/react'

function Button() {
  return (
    <button>
      <Icon name="arrow-right" size={16} color="white" />
      <span>Continue</span>
    </button>
  )
}

useIcon() Hook

Load icons imperatively with React hooks.

const { svg, loading, error } = useIcon('home')

Parameters:

name (string) - Icon slug

Returns:

{
  svg: string | null
  loading: boolean
  error: Error | null
}

Example:

import { useIcon } from 'icondev/react'

function CustomIcon({ name }) {
  const { svg, loading, error } = useIcon(name)

  if (loading) {
    return <div className="skeleton w-6 h-6" />
  }

  if (error) {
    return <span>❌</span>
  }

  return (
    <div
      className="icon"
      dangerouslySetInnerHTML={{ __html: svg }}
    />
  )
}

`<IconDevProvider>`

Provide configuration context for browser usage.

import { IconDevProvider } from 'icondev/react'

const config = {
  apiKey: 'pk_...',
  projectSlug: 'my-project',
  cdnUrl: 'https://cdn.icon.dev'
}

function App() {
  return (
    <IconDevProvider config={config}>
      <YourApp />
    </IconDevProvider>
  )
}

Browser only: IconDevProvider is required when using icons in browser environment (not needed for Node.js/SSR).

Props:

Prop	Type	Description
`config`	`IconDevConfig`	Configuration object with apiKey, projectSlug, cdnUrl
`children`	`ReactNode`	Your app components

Vue API

Import from icondev/vue for Vue 3 components and composables.

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

`<Icon>` Component

Render an icon with Vue 3.

<Icon
  name="home"
  :size="24"
  color="currentColor"
  stroke="#333"
  class="hover:scale-110"
  @load="handleLoad"
  @error="handleError"
/>

Props:

Prop	Type	Default	Description
`name`	`string`	required	Icon slug
`size`	`number \| string`	`24`	Size in pixels or CSS value
`color`	`string`	`currentColor`	Fill color
`stroke`	`string`	`currentColor`	Stroke color
`class`	`string`	`''`	CSS classes

Events:

@load - Emitted when icon loads
@error - Emitted on error (receives Error object)

Example:

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

function handleLoad() {
  console.log('Icon loaded!')
}
</script>

<template>
  <button>
    <Icon name="arrow-right" :size="16" color="white" @load="handleLoad" />
    <span>Continue</span>
  </button>
</template>

useIcon() Composable

Load icons imperatively with Vue Composition API.

<script setup>
const { svg, loading, error } = useIcon('home')
</script>

Parameters:

name (string) - Icon slug

Returns:

{
  svg: Ref<string | null>
  loading: Ref<boolean>
  error: Ref<Error | null>
}

Example:

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

const props = defineProps<{ name: string }>()
const { svg, loading, error } = useIcon(props.name)
</script>

<template>
  <div v-if="loading" class="skeleton w-6 h-6" />
  <span v-else-if="error">❌</span>
  <div v-else v-html="svg" class="icon" />
</template>

TypeScript Types

All types are exported from the main package.

import type {
  IconDevConfig,
  IconManifest,
  ManifestIcon,
  IconProps,
  LoadIconResult
} from 'icondev'

Key Types:

interface IconDevConfig {
  apiKey: string
  projectSlug: string
  cdnUrl?: string
}

interface ManifestIcon {
  slug: string
  name: string
  url: string
  version: string
  hash: string
  size?: number
  collection?: string
  updatedAt: string
}

interface IconManifest {
  apiKey: string
  projectSlug: string
  cdnUrl: string
  icons: ManifestIcon[]
  updatedAt: string
}

interface LoadIconResult {
  svg: string
}

interface IconProps {
  name: string
  size?: number | string
  color?: string
  stroke?: string
  className?: string
  style?: React.CSSProperties
  onLoad?: () => void
  onError?: (error: Error) => void
}

CLI Commands

`npx icondev init`

Interactive setup wizard that:

Prompts for your API key
Fetches your project details
Downloads all available icons metadata
Creates icondev.json configuration file
Optionally adds icondev.json to .gitignore

npx icondev init

`npx icondev sync`

Sync your local icondev.json with the latest icons from your Icon.dev project.

npx icondev sync

This command:

Updates the icons array in icondev.json
Fetches newly added icons
Updates icon metadata (name, version, hash, etc.)
Preserves your existing configuration (apiKey, projectSlug, cdnUrl)

When to use:

After uploading new icons to your project
When icons are updated in the dashboard
To ensure local config matches remote project

Error Handling

Icons handle errors gracefully with:

Error CSS class: icon-error added to failed icons
Data attribute: data-icon-error added to element
Error callback: onError prop receives error details

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

Next Steps

Framework Integration - Next.js, Nuxt, Remix
Best Practices - Performance tips
Troubleshooting - Common issues

API Reference

On this page