Documentation

icon-vista

A zero-config local CLI tool that opens a beautiful search dashboard for 200,000+ open-source icons — with one-click strictly-typed React component generation.

Getting Started

icon-vista requires Node.js 18+ and an existing React or Next.js project. You do not need to install it globally — `npx` handles everything.

Start by running the one-time initialization command inside your project root:

npx icon-vista init

The CLI will ask you two questions interactively:

Where would you like to save your icons?

Default: ./src/components/icons

Which icon provider do you want to use?

Options: iconify (default) or untitled-ui

This creates an icon-vista.json file in your project root. You only need to run init once per project.

Running the Dashboard

After initialization, launch the visual search dashboard with:

npx icon-vista

This starts a local Express server (defaulting to port 3000, auto-incrementing if busy) and automatically opens the UI in your default browser. The terminal will confirm:

🚀 icon-vista is running at http://localhost:3000
Saving icons to: ./src/components/icons

The dashboard is fully local. Nothing you do is sent to any external server (unless you are using the Iconify provider, which fetches SVGs from the public Iconify CDN on demand).

Dashboard Features

→Search: Debounced real-time search across all icons in the active provider.
→Sidebar Filters: Filter by icon pack (e.g. `lucide`, `heroicons`) and style (e.g. `line`, `solid`).
→Infinite Scroll: Icons load in batches using IntersectionObserver — no pagination.
→Customization Panel: Click any icon to configure color, size, language (TS/JS), and export style (Arrow / Standard function).
→One-click Save: Downloads the generated `.tsx` or `.jsx` component directly into your configured `savePath`.

Provider: Iconify (Open Source)

The Iconify provider is the default. It connects to the public Iconify API to search and stream SVGs on demand. No local file installation or extra dependencies are required.

It provides access to a curated whitelist of the most popular and highest-quality icon packs:

Material Design Icons (mdi)

Phosphor Icons (ph)

Lucide (lucide)

Heroicons (heroicons)

Bootstrap Icons (bi)

Tabler Icons (tabler)

Radix UI Icons

Feather Icons

Remix Icons (ri)

Carbon Icons

Ionicons (ion)

Style filtering (line / solid / duotone) is supported for Iconify by appending the style as a keyword to the Iconify search query.

Provider: Untitled UI Pro (Premium)

icon-vista includes a unique Reverse-Rendering Engine built for teams using Untitled UI Pro. Instead of reading SVG files from disk, it dynamically renders the React components from the npm package into raw SVG strings in memory, then serves them to the dashboard — completely offline.

This provider requires that you have separately purchased a license for Untitled UI Pro and have access to their private npm registry.

Setup

Step 1 — Install the package

npm install @untitledui-pro/icons

You must be authenticated with the Untitled UI private npm registry first.

Step 2 — Initialize with untitled-ui

npx icon-vista init
# → Select: untitled-ui

Step 3 — Launch

npx icon-vista

The CLI will automatically discover all available style categories (`line`, `solid`, `duotone`, `duocolor`) and index your entire library. You will see a confirmation like:

✅ Successfully indexed 3,240 premium Untitled UI icons.

Generated Component

When you save an icon, icon-vista generates a clean, production-ready React component. Here is an example of the TypeScript output for a Lucide arrow icon:

import * as React from "react";

export function ArrowRightIcon({
  width = 24,
  height = 24,
  color = "currentColor",
  ...props
}: React.SVGProps<SVGSVGElement>) {
  return (
    <svg viewBox="0 0 24 24" fill="none" stroke={color}
      strokeWidth={2} strokeLinecap="round" strokeLinejoin="round"
      width={width} height={height} {...props}>
      <path d="M5 12h14"/>
      <path d="m12 5 7 7-7 7"/>
    </svg>
  );
}

The generator automatically:

Converts all SVG attributes to camelCase JSX props (`stroke-width` → `strokeWidth`)
Strips hardcoded `width` and `height` from the SVG source, replacing them with dynamic props
Removes any existing `color` attributes to avoid conflicts with the React `color` prop
Injects {"...props} spread for full composability

Configuration File

The icon-vista.json file created at your project root controls all behavior:

{
  "savePath": "./src/components/icons",
  "provider": "iconify"
}

Key	Type	Description
savePath	string	Relative path from your project root where generated components are saved.
provider	`iconify` \| `untitled-ui`	The icon backend to use. Determines which search engine and SVG source is used.

API Reference

icon-vista runs a local Express server. These are the internal API endpoints it exposes to the dashboard UI:

GET

/api/search

Search icons. Accepts `query`, `limit`, `start`, `packs`, `styles` query params. Returns `{ icons: string[] }`.

GET

/api/svg

Fetch a raw SVG string for a given icon ID. Accepts `id` and optional `color` query params.

GET

/api/filters

Returns available `packs` and `styles` for the active provider.

GET

/api/config

Returns the active provider name: `{ provider: string }`.

POST

/api/download

Generates and writes a React component file to disk. Body: `{ icon_id, customizations }`.

POST

/api/generate-snippet

Generates and returns a React component as a string without saving. Body: `{ icon_id, customizations }`.