Overview
A read-only JSON API and static SVG files for 12,227 icons from Lucide, Font Awesome and our own KV set. Every icon has a unique, stable numeric id, which you can use to look it up or render it.
| Base URL | https://icons-lyart-nine.vercel.app |
| Auth | None. Every endpoint is public and GET only. |
| CORS | Access-Control-Allow-Origin: * on the API, the SVGs and the JSON files, so any browser origin can call it. |
| Formats | JSON (UTF-8) for the API, image/svg+xml for icons. |
Library icon | Set | type values | Icons |
|---|---|---|---|
LUCIDE | Lucide core | outline, outline-thin, outline-light, outline-bold | 1,890 × 4 weights |
LUCIDE | Lucide Lab | lab, lab-thin, lab-light, lab-bold | 357 × 4 weights |
FONTAWESOME | Font Awesome Free 7 | classic-solid, classic-regular, classic-brands | 1,422 + 169 + 572 |
KV | Our own SVGs | default (single colour), color (multi-colour) | 881 + 195 |
The Lucide weights differ only in stroke width: 1 (thin), 1.5 (light), 2 (default) and 2.5 (bold).
Quick start
Search for an icon, take its id, then render it from /svg/id/<id>.svg.
Icon object
Every endpoint returns icons in the same shape.
| Field | Type | Description |
|---|---|---|
id | number | Unique and stable across rebuilds. Use it to fetch or render the icon. |
icon | string | Library: LUCIDE, FONTAWESOME or KV. |
type | string | Style within the library, see Overview. /api/styles has the full list. |
icon_name | string | Kebab-case name, e.g. user, arrow-right. The same name can appear in several types. |
react | string | null | The React package's import name: User (lucide-react), appleCore (@lucide/lab), faUser (Font Awesome). null when no package has it (KV). |
vue | string | null | The Vue 2 name: a lucide-vue component, an @lucide/lab export, or the vue-fontawesome@2 class string (fa-solid fa-user). null when Vue 2 doesn't have it: 311 newer Lucide icons and all KV icons. |
category | string[] | Category labels from the library, e.g. ["Accounts & access"]. Can be empty. |
Search icons
Returns a page of icons that match every filter you pass. Filters combine with AND. Results are ordered by id.
Query parameters
| Name | Type | Default | Description |
|---|---|---|---|
q | string | – | Case-insensitive text search in icon_name, react and vue. A number also matches an id exactly: q=1891. |
icon | string | – | Library: LUCIDE, FONTAWESOME or KV. Not case-sensitive. |
type | string | – | An exact type, e.g. outline-bold, classic-brands, color. |
category | string | – | One exact category label, not case-sensitive, e.g. Arrows. URL-encode it: Coding%20%26%20development. |
page | integer | 1 | 1-based page number. A page past the end returns data: []. |
limit | integer | 50 | Page size, 1–500. Values outside that range are clamped. |
Response
Example requests
| What you want | Request |
|---|---|
| Anything matching "user" | /api/icons?q=user |
| An icon by id | /api/icons?q=1891 |
| Bold Lucide arrows | /api/icons?icon=LUCIDE&type=outline-bold&category=Arrows |
| Font Awesome brand logos | /api/icons?type=classic-brands&limit=100 |
| Multi-colour KV icons | /api/icons?icon=KV&type=color |
| Page 3 of every icon, 120 per page | /api/icons?page=3&limit=120 |
Get an icon by id
Returns one icon object. An unknown id returns 404 {"error":"Icon not found"}.
List categories
Returns every category label with its icon count, sorted A–Z. Pass icon to count one library only. Use a name as the category filter in /api/icons.
| Name | Type | Description |
|---|---|---|
icon | string, optional | LUCIDE, FONTAWESOME or KV. |
List types (styles)
Returns every type with usage details: the stroke width for Lucide types, and the npm package that exports the React and Vue 2 definitions for Font Awesome types. Also available as a static file at /styles.json.
Download the full list
Returns every icon as one array of icon objects, about 2.7 MB. To load everything at once, prefer the static copy at /icons.json, which Vercel serves from its CDN.
Static SVG & JSON files
These are plain files on the CDN. Fetching them doesn't call the API.
| Path | Content |
|---|---|
/svg/id/<id>.svg | An icon's SVG by unique id. This is the recommended way to render. |
/svg/<icon>/<type>/<icon_name>.svg | The same SVG by name, e.g. /svg/lucide/outline-bold/user.svg, /svg/fontawesome/classic-brands/github.svg. <icon> is lowercase. |
/svg/color-ids.json | The ids of multi-colour icons, which should be rendered as images rather than masks. |
/icons.json | Every icon object (the same as /api/icons.json). |
/styles.json | Every type (the same as /api/styles). |
Errors
Errors return a JSON body with an error message. Bad query values never cause an error: unknown filters match nothing, and page and limit are clamped.
| Status | When | Body |
|---|---|---|
200 | Success, including searches with no matches ("total": 0) | The result |
404 | Unknown id in /api/icons/:id | {"error":"Icon not found"} |
404 | Unknown /api/* route | {"error":"Not found"} |
404 | Unknown SVG path | An empty or plain 404 response |
Fetching examples: search & filters
Fetching examples: icons by id
/svg/id/<id>.svg works on its own; see Rendering icons.Fetching examples: pagination
Use total and limit to work out how many pages there are: Math.ceil(total / limit).
Fetching examples: TypeScript client
A small typed client you can copy into a project. It has no dependencies.
Fetching examples: React hook
Fetching examples: Vue 2
Fetching examples: Node script
Ways to render an icon
| Method | Colour | Use when |
|---|---|---|
<img src="/svg/id/…"> | The SVG's own colours | Multi-colour icons, emails, simplest markup |
CSS mask | Any colour; follows currentColor | Single-colour icons that should match the surrounding text (dark mode, hover states) |
Inline <svg> (fetched text) | Full CSS control | Animating or styling individual paths |
| The library's own package | The package's props | Lucide or Font Awesome icons bundled into your app (use the react and vue fields) |
React <KfIcon> component
Renders any icon from its id. Single-colour icons follow color or the text colour. Multi-colour icons keep their own colours. There's no API call per icon: it loads the static SVG plus /svg/color-ids.json once.
Multi-colour icons
195 KV icons have type: "color". A CSS mask would flatten them to one colour, so render them as images. Their ids are listed in /svg/color-ids.json; the type field tells you the same thing.
IDs, caching & limits
- Stable ids: an icon keeps its
idacross rebuilds and package upgrades. New icons get new, higher ids, so it's safe to store ids in your database. - The same name in several types:
userexists in every Lucide weight and Font Awesome style, each with its ownid. Filter byiconandtypeto get exactly one. - SVG caching: browsers cache SVGs for 1 hour and the CDN for 1 day. If an icon's artwork changes, add a version parameter to the URL (
/svg/id/1772.svg?v=2) so clients fetch the new file. - API responses are not cached by the browser, so search results are always current.
- Page size: at most 500 per request. To load everything, use
/icons.json(about 2.7 MB) instead of paging through the API. - Search is a case-insensitive substring match on
icon_name,reactandvue. A number also matches an id exactly. Categories are filtered separately withcategory. - Licences: Lucide is ISC, Font Awesome Free icons are CC BY 4.0, and KV icons are internal.
Playground
Build a request and run it against this server.