Semantic Icons

How it ranks

Retrieval, not a file name lookup.

Every mark carries a phrase, a category and about 18 search tags — synonyms, both regional spellings, and the whole sentences a caller types. A query is stemmed, stripped of stopwords, and scored against all of it. Nothing here is a model call.

01

Reduce the words

Stopwords go. Plurals and verb endings fold to a stem, so tomatoes meets tomato. Accents fold too.

02

Score every mark

Each term pays by where it sits, times how rare it is in the set, times how much of the query the mark answers.

03

Pay the exact hits

A whole phrase found inside the prose outranks a longer phrase that shares one word, so put on your raincoat is a raincoat.

04

Guard against a thief

A term counts at most twice across one mark's tags, so a long tag list widens reach without taking another mark's own name.

Signal	Why it counts	Weight
Term in the phrase	The mark is named for this idea	6
Term in a keyword	A synonym, or how a person says it	4
Term in the category	Weak, but it breaks a tie	1
Exact phrase	The query is the mark’s own name	140
Exact keyword	The query is a listed synonym	100
Exact keyword, shaded	… but the query names another mark outright	30
Phrase inside the prose	Per word, so longer is stronger	40
Keyword inside the prose	Per word	14

Browse

Every mark, by category.

Filter by name or keyword, set the size you ship at, and click any mark to copy its SVG.

When the words do not match

Three stages, and only the last one draws.

Word search cannot answer a word the set never names. A phrase under the score floor goes to the semantic-icon function, which first looks for the nearest curated mark by meaning, and pays a model to draw only when nothing is close. The panel below replays that path with prepared results.

stage 1

Words, in the page

The lexical index over all 3006 marks. No key, no request, no model. This answers most prose.

stage 2

Meaning, in the database

A voyage-3 vector per mark in pgvector. match_icons returns the nearest by cosine distance, above a floor of 0.62.

stage 3

A new mark

Only when nothing is close. The model states a concept, draws, passes the geometry check, and the mark is cached.

Preview resolve(phrase)

Pick a phrase the set does not hold

Word search over 3006 curated marks
Best score is under the floor of 8
Nearest mark by meaning is under 0.62 similarity
Send the phrase to the drawing service
Check the geometry, then cache the mark

This panel is a preview. It makes no network call, and this page runs stage 1 only. The four marks were drawn by hand for this page, in the same 24-unit contract as the set. Each phrase is a real miss: the word search returns nothing for all four.

Waiting no phrase yet

Pick a phrase on the left to replay the path.

Use it

A package, an SDK, and an MCP server.

The set ships inside the package, so a curated phrase costs no request and no key.

Install npm install semantic-icons

One package. /web, /native, /sdk and /library below are import paths inside it, not separate packages.

React/web · /native

// React and Next.js render inline SVG.
import { SemanticIcon }
  from 'semantic-icons/web';

// React Native renders through
// react-native-svg. Same component,
// same props, one import away.
import { SemanticIcon }
  from 'semantic-icons/native';

configureSemanticIcons({
  functionUrl,
  anonKey,
  resolveLocally: createLocalResolver(),
});

<SemanticIcon phrase="time for bed" />

SDKsemantic-icons/sdk

// No framework. Node and the browser.
import { createSemanticIcons }
  from 'semantic-icons/sdk';

const icons = createSemanticIcons({
  functionUrl,
  anonKey,
});

icons.search('my phone battery is low');
icons.get('battery-low');

// Curated first, then the model.
await icons.resolve('a barnacle');

MCPsemantic-icons-mcp

# Give an assistant the whole set.
claude mcp add semantic-icons \
  -- npx -y semantic-icons-mcp

# Tools it gains:
#   search_icons     rank prose
#   get_icon         one mark by name
#   list_categories  the 71 groups
#   list_category    one group
#   resolve_icon     curated, then model

Custom sets

Need 300 icons in your house style?

A set is a contract: one grid, one stroke width, one hand. Fifty icons drawn by four people over two years do not form a set. We already run that contract over 3006 icons, with the geometry checked in the build and every mark reviewed in a grid at 16 px.

You send

The icons you already have, however few.
Your grid and stroke width, or we read them from your files.
The list of what is missing, in plain words.

You get

Every icon drawn to your contract, not ours.
The same prose search over your set.
The source, the checks, and the build that keeps it consistent.

How it runs

A sample of ten icons first, so you can judge the hand.
Then the rest, in batches you review.
Fixed price, agreed before the sample.

Tell us what you need Say roughly how many icons and what you already have. A reply comes from a person.

Questions

Asked and answered.

What is Semantic Icons?

A curated set of 3006 SVG icons drawn to one contract, and a search that takes plain prose. Every icon uses a 24 by 24 view box, a 2 unit stroke and currentColor, so the whole set matches and follows your text colour.

How do I search for an icon without knowing its name?

Type what you would say. The ranker reduces your sentence to word stems, scores every icon on its phrase, keywords and category, weights each hit by how rare the term is, and rewards icons that cover more of your query.

Does the search send my query anywhere?

No. The ranking runs in this page over a static index, with no request and no key. A vector search and icon generation are separate stages that only run when the words in the page find nothing.

How many keywords does each icon carry?

About seventeen. That is what makes a sentence work as a query. An icon with four keywords can only be found by its own name and near synonyms.

Can I use the icons in a commercial product?

Yes. The icon set, the search, the SDK and the MCP server are MIT. Use them in anything, change them, redistribute them, and sell what you build. No credit is needed in your interface. Every mark is drawn for this set, no artwork is copied, and brand logos are left out on purpose.

Is Semantic Icons free?

The set and the search are free, and the search needs no key because it runs in your page. Only one thing is paid: a drawing of an icon that does not exist yet, because that calls a model.

What does the icon generation API cost?

One credit per new drawing. Credits are prepaid, so there is no invoice and no surprise bill. A cache hit, a curated icon and a nearest match by meaning all cost nothing, and they keep working when the balance reaches zero. A drawing that fails is refunded.

Do I need an API key?

Only to draw a new icon. Search, the SDK and the MCP server work with no key and no request. The hosted endpoint needs a key on every route, and the key is stored only as a hash.

Can I get a set of icons in my own house style?

Yes. We run the same drawing contract over your grid and your stroke width, starting with a sample of ten icons so you can judge the hand before the rest is drawn. The price is fixed and agreed first.

Is there an SDK or an MCP server?

Both. The SDK needs no framework and runs in Node and the browser. The MCP server gives a coding assistant five tools, so it searches the real set instead of guessing a file name.

More in the writing: what we measured while drawing 3006 icons and making them findable from plain prose.

Ask for an icon the wayyou would say it.