iconmate

Add SVG icons to your JS apps without icon libraries.

Quick Start · Install · Presets · CLI Commands · AI Ready · Configuration

Built from my blog post on Why you might not need an icon library, iconmate is a Rust-powered CLI for developers who want the speed and control of plain files without icon-package bloat.

Use icones.js.org, a direct SVG URL, or raw SVG markup. iconmate drops the icon straight into your project and keeps your exports tidy.

Why iconmate?

Made with Rust🦀: Fast TUI that you can use on any IDE (powered by ratatui, nucleo).
AI-ready automation 🤖: Let your coding agents get icons and add it to your project! A CLI is basically an MCP, just let AI use iconmate --help and it should be able to get everything running!
Zero dependencies 📦: No icon library runtime added to your app
Framework-native output 🧩: Generate files for React, Vue, Svelte, Solid, or plain SVG
Interactive by default 🎮: Run iconmate and have a pleasant interactive TUI
Multiple sources 🌐: Pull icons from Iconify names, URLs, or even raw SVG (which means it works with your private icon packs i.e. Anron)
Fast workflow ⚡: Generate file + export line in one step
Prototype-friendly 🏗️: Create empty SVG placeholders when needed

Quick Start

# Install
npm install -g iconmate

# Run the TUI in your project 🚀
iconmate

✨ That's it. The interactive TUI guides you through adding icons to your project.

// 👇 Then, you can just easily use any icon on your project like this!

import { IconHeart } from "@/assets/icons";

function MyApp() {
  return <IconHeart />;
}

Configuration

You can also add sensible defaults by passing flags as configs:

iconmate --folder src/components/Icons/ --folder src/components/icons
iconmate --folder src/components/Icons/ --icon heroicons:heart --name Heart

Iconmate now includes config schemas + TS type definitions in the repo:

Local config schema (repo): iconmatelocal.schema.json
Global config schema (repo): iconmateglobal.schema.json
Local config schema (raw): https://raw.githubusercontent.com/Blankeos/iconmate/main/iconmatelocal.schema.json
Global config schema (raw): https://raw.githubusercontent.com/Blankeos/iconmate/main/iconmateglobal.schema.json
Schema source: config-gen/src/schema.ts
TS type definitions: config-gen/src/types.ts

Regenerate schemas from project root:

just config-schema

just config-schema installs config-gen deps and generates both schema files.

Local Config (`iconmate.config.json`)

{
  "$schema": "https://raw.githubusercontent.com/Blankeos/iconmate/main/iconmatelocal.schema.json",
  "folder": "src/assets/icons",
  "preset": "normal",
  "output_line_template": "export { default as Icon%name% } from './%icon%%ext%';",
  "svg_view_cmd": "zed %filename%"
}

Use the raw URL for $schema so editors can fetch JSON directly.

Local config keys:

folder (default: src/assets/icons)
preset (default: normal, meaning plain .svg mode)
output_line_template (default: export { default as Icon%name% } from './%icon%%ext%';)
svg_view_cmd (supports %filename% token)

Allowed preset values:

normal (plain SVG mode)
react
svelte
solid
vue
emptysvg

Global Config (user-level)

Global config is for user-wide defaults and currently documents svg_view_cmd.

Suggested paths:

macOS: ~/Library/Application Support/iconmate/config.json
Linux: ~/.config/iconmate/config.json
Windows: %APPDATA%\\iconmate\\config.json

Example global config:

{
  "$schema": "https://raw.githubusercontent.com/Blankeos/iconmate/main/iconmatelocal.schema.json",
  "svg_view_cmd": "code %filename%"
}

Note

This release adds config schemas and generated docs/types. Runtime loading/precedence wiring in the CLI/TUI is tracked in folder-system-plan.md.

Installation

npm install -g iconmate  # npm (or use npx)
bun install -g iconmate  # or bun (or use bunx)
cargo binstall iconmate  # or cargo-binstall (prebuilt binary, faster)
cargo install iconmate   # or cargo (build from source)
curl -sSL https://raw.githubusercontent.com/Blankeos/iconmate/main/install.sh | sh # or linux/macos (via curl)

Framework Presets

Determines the output filetype and the contents inside that file type.

Preset	File Type	Framework
`normal`	`.svg`	Vanilla HTML/CSS
`react`	`.tsx`	React Components
`svelte`	`.svelte`	Svelte Components
`solid`	`.tsx`	Solid Components
`vue`	`.vue`	Vue Components
`emptysvg`	`.svg`	Placeholder

Important

If you want to use .svg file types, make sure to setup svgr for your js apps. I covered how to do this in:

SolidJS (Vite)
React (Vite)
React (NextJS)
Vue - contribution welcome!
Svelte - couldn't find an svgr integration. Just use the svg preset.

Command Line

Interactive TUI Mode (Recommended)

iconmate

This section is helpful for AI:

Add Specific Icon

iconmate add --folder src/assets/icons --icon heroicons:heart --name Heart

With URL

iconmate add --folder src/assets/icons --icon https://api.iconify.design/mdi:heart.svg --name Heart

Raw SVG Content

iconmate add --folder src/assets/icons --icon '<svg>...</svg>' --name Heart

You can also pull raw SVG directly from the Iconify API:

iconmate add --folder src/assets/icons --icon "$(curl -fsSL https://api.iconify.design/mdi:heart.svg)" --name Heart

Custom Export Template

iconmate add --folder src/assets/icons --icon heroicons:heart --name Heart --output-line-template "export { ReactComponent as Icon%name% } from './%icon%.svg?react';"

Delete icons

iconmate delete --folder src/assets/icons

List current icons

iconmate list --folder src/assets/icons
# or use the default folder (src/assets/icons)
iconmate list

Iconify API Commands

# Search by keyword (text: one prefix:icon per line)
iconmate iconify search heart

# Search with pagination and JSON output
iconmate iconify search heart --limit 20 --start 0 --format json

# Include collection metadata in JSON search output
iconmate iconify search heart --format json --include-collections

# List all available collections
iconmate iconify collections

# List icons from one collection prefix
iconmate iconify collection mdi

# Get one icon as raw SVG (default)
iconmate iconify get mdi:heart

# Get one icon as raw Iconify JSON
iconmate iconify get mdi:heart --format json

iconmate iconify get <prefix:icon> --format json uses Iconify's JSON endpoint format, for example https://api.iconify.design/mdi.json?icons=heart.

AI-Ready Workflows

iconmate is designed to be easy for AI agents and scripts to drive end-to-end.

# 1) Search in machine-readable JSON
iconmate iconify search heart --format json --limit 20 --include-collections

# 2) Add an icon non-interactively from prefix:name
iconmate add --folder src/assets/icons --icon mdi:heart --name Heart

# 3) Or fetch raw SVG from Iconify API and add directly
iconmate add --folder src/assets/icons --icon "$(curl -fsSL https://api.iconify.design/mdi:heart.svg)" --name Heart

This means an AI can search, choose, and add icons without opening a browser.

Agent Skill

For the best AI experience, install the iconmate skill so your agent knows all the commands automatically:

npx skills add Blankeos/iconmate

Package.json Scripts

Best practice: Add sensible defaults to your script runner.

"scripts": {
  // Usage: npm run iconmate (usually this is the only command you need)!
  "iconmate": "iconmate --folder src/assets/icons/"
}

Supported Platforms

macOS (Intel & Apple Silicon) 🍎
Linux (x64 & ARM64) 🐧
Windows (x64) 🪟

How It Works

Find your icon: Use https://icones.js.org or iconmate iconify search <query>.
Pick the icon id: For example heroicons:heart.
Add with iconmate: Interactive (iconmate) or direct (iconmate add ...).

Why this structure?

Copy-paste workflow: Find icon on icones.js.org → copy name → paste into iconmate
Organized by default: Everything goes into index.ts exports automatically and just typing <Icon will autosuggest from your current collection. Just regular TS behavior.
TypeScript ready: Generated code is fully typed. Pass custom width, height, fills, you name it.
Customizable 🎨: Want to add a default Tailwind class on every icon? custom props? Just add it to the file!
Git-friendly: Plain SVG files, no binary assets
Lightning fast: Native Rust binary, no Node.js startup time

Contributing

Contributions are welcome—pull requests for bug fixes, new framework presets, or improvements are appreciated.

🐱 Repo: github.com/Blankeos/iconmate - Star it if you love it ⭐

What's Completed from the Roadmap

✅ Interactive prompt mode
✅ Framework presets (React, Vue, Svelte, Solid)
✅ URL and raw SVG support
✅ Custom export templates
✅ Zero-config installation

Roadmap & Out-of-scoped

Near-Term Roadmap

Made with Rust 🦀 | Based on my blog post

Name		Name	Last commit message	Last commit date
Latest commit History 72 Commits
.claude/commands		.claude/commands
.github/workflows		.github/workflows
_docs		_docs
config-gen		config-gen
npm		npm
skills/iconmate		skills/iconmate
src		src
tests		tests
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Justfile		Justfile
README.md		README.md
TODOS.md		TODOS.md
dist-workspace.toml		dist-workspace.toml
folder-system-plan.md		folder-system-plan.md
iconify-cli-plan.md		iconify-cli-plan.md
iconmate.jsonc		iconmate.jsonc
iconmateglobal.schema.json		iconmateglobal.schema.json
iconmatelocal.schema.json		iconmatelocal.schema.json
install.sh		install.sh
manual_test.sh		manual_test.sh
tag_and_release.sh		tag_and_release.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

iconmate

Why iconmate?

Quick Start

Configuration

Local Config (`iconmate.config.json`)

Global Config (user-level)

Installation

Framework Presets

Command Line

Interactive TUI Mode (Recommended)

Add Specific Icon

With URL

Raw SVG Content

Custom Export Template

Delete icons

List current icons

Iconify API Commands

AI-Ready Workflows

Agent Skill

Package.json Scripts

Supported Platforms

How It Works

Why this structure?

Contributing

What's Completed from the Roadmap

Roadmap & Out-of-scoped

Near-Term Roadmap

About

Uh oh!

Releases 5

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

iconmate

Why iconmate?

Quick Start

Configuration

Local Config (iconmate.config.json)

Global Config (user-level)

Installation

Framework Presets

Command Line

Interactive TUI Mode (Recommended)

Add Specific Icon

With URL

Raw SVG Content

Custom Export Template

Delete icons

List current icons

Iconify API Commands

AI-Ready Workflows

Agent Skill

Package.json Scripts

Supported Platforms

How It Works

Why this structure?

Contributing

What's Completed from the Roadmap

Roadmap & Out-of-scoped

Near-Term Roadmap

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Local Config (`iconmate.config.json`)

Packages