iconvaultkit

TypeScript client for searching and fetching icons from 200,000+ open-source icons across 100+ libraries — Material Design, Lucide, Heroicons, Phosphor, Tabler, Font Awesome, and more.

Zero dependencies. Works in Node.js, Bun, Deno, and the browser.

Install

npm install iconvaultkit

Quick start

import { searchIcons, getIconSvg, listCollections } from "iconvaultkit"

// Search across all libraries
const result = await searchIcons("home")
console.log(result.icons)
// ["mdi:home", "lucide:home", "heroicons:home", ...]

// Search within one library
const lucideResult = await searchIcons("arrow right", { collection: "lucide", limit: 5 })

// Get SVG markup
const svg = await getIconSvg("lucide", "home", { color: "#6366f1", size: 24 })
// <svg xmlns="http://www.w3.org/2000/svg" ...>...</svg>

// List all available libraries
const libraries = listCollections()
// [{ prefix: "mdi", name: "Material Design Icons" }, ...]

API

Standalone functions

import {
  searchIcons,
  getIconSvg,
  listCollections,
  getCollectionIcons,
  searchAndGetSvg,
  parseIconId,
} from "iconvaultkit"

searchIcons(query, options?)

Search icons by keyword.

| Option | Type | Default | Description | |---|---|---|---| | collection | LibraryPrefix | all libraries | Restrict to one library | | limit | number | 20 | Max results (max 100) | | start | number | 0 | Pagination offset |

Returns Promise<SearchResult> with { icons: string[], total: number, start: number, limit: number }.

getIconSvg(collection, name, options?)

Fetch the SVG markup for a specific icon.

| Option | Type | Default | Description | |---|---|---|---| | color | string | "currentColor" | Any CSS color value | | size | number | 24 | Sets width and height | | width | number | 24 | Width in pixels | | height | number | 24 | Height in pixels |

Returns Promise<string> — raw SVG markup.

listCollections()

Returns all available icon libraries as Collection[] — { prefix: string, name: string }[]. Synchronous, no network request.

getCollectionIcons(collection, options?)

Browse all icons in a specific library.

| Option | Type | Default | Description | |---|---|---|---| | limit | number | 200 | Max icons to return |

Returns Promise<string[]> — icon IDs in "collection:name" format.

searchAndGetSvg(query, searchOptions?, svgOptions?)

Convenience: search and immediately fetch the SVG of the top result. Returns Promise<{ iconId: string; svg: string } | null>.

parseIconId(iconId)

Parse "lucide:home" into { collection: "lucide", name: "home" }. Synchronous.

Class API

import { IconVaultKit } from "iconvaultkit"

// Use a custom base URL (e.g. your own Iconify proxy)
const client = new IconVaultKit({ baseUrl: "https://your-proxy.example.com" })

const result = await client.search("home", { collection: "lucide" })
const svg    = await client.getSvg("lucide", "home", { size: 32 })

All standalone functions are convenience wrappers over a shared IconVaultKit instance.

React

Drop-in <Icon /> component, similar to @iconify/react — no icon data to bundle, SVG is fetched on demand and cached in memory.

npm install iconvaultkit react

import { Icon } from "iconvaultkit/react"

<Icon icon="lucide:home" />
<Icon icon="mdi:account-box-outline" width={32} color="#6366f1" />
<Icon icon="tabler:refresh" rotate={180} />

<Icon /> props

| Prop | Type | Default | Description | |---|---|---|---| | icon | string | — | Icon ID, "collection:name" (required) | | width / height | number | 24 | Dimensions in pixels | | size | number | — | Shorthand for setting width and height together | | color | string | "currentColor" | Any CSS color value | | rotate | 90 \| 180 \| 270 | — | Rotate the icon | | hFlip / vFlip / flip | boolean | — | Flip horizontally / vertically / both | | inline | boolean | false | Align like a glyph font instead of a block | | onLoad | () => void | — | Called once the SVG has loaded | | baseUrl | string | Iconify public API | Use your own Iconify-compatible proxy | | className / style | — | — | Passed to the wrapping <span> |

There's also InlineIcon, equivalent to <Icon inline />.

This component ships its own "use client" directive, so it works directly inside Next.js App Router Server Components without you needing to add the directive yourself.

TypeScript

The package ships full TypeScript types including a LibraryPrefix union type that gives autocomplete for all 80+ known library prefixes:

import type { LibraryPrefix, SearchResult, SvgOptions } from "iconvaultkit"

const collection: LibraryPrefix = "lucide" // autocompletes all known prefixes

Supported libraries

80+ libraries including:

Material Design Icons, Lucide, Heroicons, Phosphor, Solar, Tabler, Font Awesome 5/6/7, Bootstrap Icons, Feather, Remix Icon, Ant Design, Radix Icons, Flowbite, Octicons, Carbon, Unicons, Clarity, and more.

Call listCollections() to get the full list with display names.

License

MIT — iconvaultkit.com