CLI

The package ships one executable, icons. It reads the same metadata.json and embeddings.json that come inside the package, so there is nothing to sync and nothing to sign in to.

Terminal
# Without installing anything
npx @devigner-ui/icons search "upload progress"

# Or install it globally
npm install -g @devigner-ui/icons
icons search "upload progress"

Inside a project that already depends on the package, your package runner will find it: pnpm icons list, npx icons list.

Commands

Command What it does
search <query> Rank every icon against a description
list List icons, with filters
info <name> Show one icon's metadata
categories List categories and their counts
copy <name> Print an icon as a React snippet or as SVG
migrate [dir] Rewrite renamed icons to their current names

Global options

Output
-h, --help          Show help
-v, --version       Show the package version
    --format <fmt>  table (default), json or names
    --json          Shorthand for --format=json

Notes and warnings are written to stderr, so --json output stays pipeable.

Ranks all 2,496 icons against a plain description. One vector per icon, not one per drawing.

Terminal
icons search <query> [options]
Option Description Default
-l, --limit <n> Results to show 10
-t, --threshold <n> Lowest score to keep, 0 to 1 0.15
-c, --category <cat> Restrict to one category all
--keyword Match words instead of loading the model false
Terminal
icons search "upload progress"
icons search "user profile sidebar" --limit=5 --threshold=0.2
icons search "map pin" --category=location-maps
Output
Name               Score  Category
-----------------  -----  ----------------
UploadTrackQuaver  64%    media-playback
UploadTrack        64%    media-playback
Upload             62%    arrows-direction
UploadTray         60%    arrows-direction
UploadSquare       59%    arrows-direction

How ranking works

Every icon's name, category, keywords and intended use were embedded as one 384-dimension vector, and those vectors ship in the package as embeddings.json. Ranking is the cosine between your query's vector and each of them, the same file and the same arithmetic the website's search runs in your browser.

Embedding the query is the one part the shipped file cannot do for itself, and it needs the model that produced the vectors:

Terminal
npm install @xenova/transformers

That is not a dependency of this package; installing icons does not pull a machine-learning runtime into your project. Without it, search ranks by keyword instead and says so on stderr. --keyword asks for that path directly, which is also the fast one: no model to load.

list

Terminal
icons list [options]
Option Description
-c, --category <cat> Filter by category
-s, --style <style> outline, twotone, bold, bulk or broken
-l, --limit <n> Stop after n
Terminal
icons list --category=shopping-ecommerce --limit=4
icons list --style=bulk --format=names
icons list --format=json
Output
Name            Category            Styles
--------------  ------------------  ------------------------------------
Bag             shopping-ecommerce  outline, twotone, bold, bulk, broken
BagCheck        shopping-ecommerce  outline, twotone, bold, bulk, broken
BagCross        shopping-ecommerce  outline, twotone, bold, bulk, broken
BagCrossCircle  shopping-ecommerce  outline, twotone, bold, bulk, broken

There is no --free-only or --pro-only. Every style of every icon is free, so one would return the whole set and the other nothing.

copy

Terminal
icons copy <name> [options]
Option Description Default
-s, --style <style> outline, twotone, bold, bulk or broken outline
-f, --format <fmt> tsx or svg tsx
-o, --out <dir> Write files there instead of printing print
--clipboard Also put the output on the clipboard false

A name containing * is treated as a glob.

Terminal
icons copy ShoppingCart
icons copy ShoppingCart --style=bold
icons copy ShoppingCart --format=svg
icons copy "Arrow*" --format=svg --out=./arrows

tsx prints the import and the element, with the props that style needs:

TSX
import { IconShoppingCart } from "@devigner-ui/icons";

<IconShoppingCart variant="Bold" className="h-6 w-6" />

svg renders the component you installed rather than reading from a second copy of the artwork, so what you get is exactly what the component draws. That means it needs react and react-dom, both already peer dependencies of this package, so it works in any project that installed it, and only fails under a bare npx with nothing else around.

Every style is available on every icon, so --style always gives you the one you asked for. bulk used to fall back to outline on gated icons; it does not any more, because nothing is gated.

info

Terminal
icons info ShoppingCart
Output
Icon: ShoppingCart
Display name: Shopping Cart
Category: shopping-ecommerce
Keywords: shopping, cart, buy, store, checkout, basket
Paths: 17
Styles:
  outline: free
  twotone: free
  bold: free
  bulk: free
  broken: free
Usage: cart, checkout, storefront, orders

An icon's former name works too, with a note on stderr naming the current one. The same goes for copy, and search matches former names:

Terminal
icons info Bag2
Output
note: Bag2 was renamed to BagStraps
Icon: BagStraps
...

migrate

Rewrites old icon names to current ones across a project. See Migrate to 3.5 for why icons were renamed, and the codemod page for a walkthrough.

Terminal
npx @devigner-ui/icons migrate --dry   # list what would change
npx @devigner-ui/icons migrate         # the current directory
npx @devigner-ui/icons migrate src     # one directory
Option Description
--dry List what would change without writing

It changes only spellings that can mean nothing else: component names (IconBag2), package subpaths (@devigner-ui/icons/Bag2), SVG file paths (icons-svg/svg/outline/Bag2.svg) and sprite ids (#Bag2 in an href). An old name in a plain string, such as a lookup key, could be anything, so it is listed for you to check instead of changed. node_modules and build output are skipped.

When there is nothing to change it prints No old icon names found., which makes migrate --dry usable as a check in CI; see Upcoming 4.0.

Output
updated src/App.tsx (3)
Updated 3 references in 1 file.

Check these by hand: they are strings, not imports.
src/icons.ts:12  "Bag2" may be an icon name, now "BagStraps"

It knows every rename ever made, so it still works after the old names have been removed in a major release.

categories

Terminal
icons categories
Output
media-playback (188)
arrows-direction (166)
system-ui (125)
design-layout (119)
reactions-emojis (90)
...

Exit codes

Code Meaning
0 Success
1 General error
2 Invalid arguments
3 Icon not found

Documentation

Browse all 12,480 icons