AppIconsKit
npm Package

iconvaultkit

TypeScript client for searching and fetching icons from 200,000+ open-source icons across 90+ libraries. Zero dependencies. Works in Node.js, Bun, Deno, and the browser.

View on npm·Looking for the MCP server?

Install

bash
npm install iconvaultkit

Quick start

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

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

// Search within one library
const lucide = 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" width="24" ...>...</svg>

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

Class API

All standalone functions use a shared default instance. Use the class directly when you need a custom base URL (e.g. a self-hosted Iconify proxy).

typescript
import { IconVaultKit } from "iconvaultkit"

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 })

Functions

searchIcons(query, options?)

Search icons by keyword across all (or one) library.

Parameters

querystringKeyword to search for
options.collectionLibraryPrefixoptionalRestrict to one library prefix, e.g. 'lucide'
options.limitnumberoptionalMax results, default 20, max 100
options.startnumberoptionalPagination offset, default 0

Returns

Promise<SearchResult>

Example

const result = await searchIcons("home", { collection: "lucide", limit: 5 })
// result.icons → ["lucide:home", "lucide:home-3d", ...]
// result.total → 1
getIconSvg(collection, name, options?)

Fetch the SVG markup for a specific icon.

Parameters

collectionstringLibrary prefix, e.g. 'lucide'
namestringIcon name, e.g. 'home'
options.colorstringoptionalCSS color value, default 'currentColor'
options.sizenumberoptionalSets width and height, default 24
options.widthnumberoptionalWidth in pixels
options.heightnumberoptionalHeight in pixels

Returns

Promise<string> — raw SVG markup

Example

const svg = await getIconSvg("lucide", "home", { color: "#6366f1", size: 32 })
// → '<svg xmlns="http://www.w3.org/2000/svg" width="32" ...>...</svg>'
listCollections()

List all 90+ available icon libraries. Synchronous, no network request.

Returns

Collection[] — { prefix: string, name: string }[]

Example

const libs = listCollections()
// → [{ prefix: "mdi", name: "Material Design Icons" }, ...]
getCollectionIcons(collection, options?)

Browse all icons in a specific library.

Parameters

collectionstringLibrary prefix, e.g. 'heroicons'
options.limitnumberoptionalMax icons to return, default 200

Returns

Promise<string[]> — icon IDs in 'collection:name' format

Example

const icons = await getCollectionIcons("heroicons", { limit: 10 })
// → ["heroicons:home", "heroicons:user", ...]
searchAndGetSvg(query, searchOptions?, svgOptions?)

Convenience: search and immediately return the SVG of the top result.

Parameters

querystringKeyword to search for
searchOptionsSearchOptionsoptionalSame options as searchIcons
svgOptionsSvgOptionsoptionalSame options as getIconSvg

Returns

Promise<{ iconId: string; svg: string } | null>

Example

const result = await searchAndGetSvg("home", { collection: "lucide" }, { size: 24 })
// result.iconId → "lucide:home"
// result.svg    → '<svg ...>...</svg>'
parseIconId(iconId)

Parse a 'collection:name' icon ID into its parts. Synchronous.

Parameters

iconIdstringIcon ID in 'collection:name' format

Returns

{ collection: string, name: string }

Example

const { collection, name } = parseIconId("lucide:arrow-right")
// collection → "lucide"
// name       → "arrow-right"

TypeScript

The package ships full declarations including a LibraryPrefix union type that autocompletes all 90+ known library prefixes.

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

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

async function getHomeIcon(lib: LibraryPrefix): Promise<string> {
  return getIconSvg(lib, "home", { size: 24 })
}

Common use cases

Write an icon to a file

typescript
import { getIconSvg } from "iconvaultkit"
import { writeFileSync } from "fs"

const svg = await getIconSvg("lucide", "home", { color: "#000", size: 48 })
writeFileSync("home.svg", svg)

Build a custom icon picker

typescript
import { searchIcons, getIconSvg, parseIconId } from "iconvaultkit"

// Search
const { icons } = await searchIcons(userInput, { limit: 20 })

// User picks one — fetch its SVG
const { collection, name } = parseIconId(icons[0])
const svg = await getIconSvg(collection, name, { size: 24 })

Find an icon and use it in one call

typescript
import { searchAndGetSvg } from "iconvaultkit"

const result = await searchAndGetSvg("settings", { collection: "heroicons" }, { size: 20 })
if (result) {
  console.log(result.iconId) // "heroicons:cog-6-tooth"
  console.log(result.svg)    // <svg ...>...</svg>
}

Links