icons

name	icons
description	Find, fetch, and install the right icon or logo from the right source — brand marks, country flags, file-type icons (PDF, DOCX, ZIP), and UI glyphs — and keep them visually consistent with the app. Use when the project's icon library has no match, when svgl comes up empty, or when the user asks for a flag, a file-type badge, a brand logo, or just "an icon for X". Covers the Iconify search API (200k+ icons across flags, file types, logos and UI sets), the svgl shadcn registry for full-colour brand logos, family and stroke-weight matching so a borrowed icon does not look pasted in, and why svgrepo and flaticon cannot be fetched programmatically. Triggers on "lisää ikoni", "maan lippu", "flag icon", "PDF icon", "file type icon", "brand logo", "sign in with Google/GitHub", "language switcher", "svgl", "iconify", "find an icon". For overall visual direction rather than sourcing one specific mark, use ui-signature; for installing shadcn components generally, use shadcn.
license	MIT

Sourcing icons

An icon is wrong when it is the wrong family, not when it is the wrong shape. Pick the source by what kind of mark it is, then match it to what the app already uses.

Route by mark type

Need	Source	Why
App UI glyph (menu, upload, search)	project's existing library — Lucide in shadcn projects	never add a second family for a glyph the current one has
Country flag	Iconify circle-flags / flag / flagpack	real flag geometry, MIT, no emoji-font dependency
File type (PDF, DOCX, ZIP)	Iconify vscode-icons / catppuccin / material-icon-theme (colour), or lucide:file-text (mono)	pick colour or mono to match the surrounding UI, not both
Brand logo, full colour, light/dark variants	svgl	curated, has wordmarks and theme variants
Tech / infra logo (OpenShift, Docker, Postgres, Redis)	Iconify logos (1800+, CC0), devicon, skill-icons	svgl has almost none of these; logos covers the whole stack in colour
Brand logo, monochrome long tail	Iconify simple-icons (3400+, CC0)	covers brands svgl does not
Anything else	Iconify search across all sets	200k+ icons, one API

Check the project's own library first: lucide:file-text, lucide:flag, lucide:file and friends exist, and one family stays one family.

Iconify — the general engine

Public API, no auth, no key. Search returns prefix:name ids.

# search everything
curl -s "https://api.iconify.design/search?query=pdf&limit=32"

# constrain to sets you actually want (this is the important flag)
curl -s "https://api.iconify.design/search?query=pdf&prefixes=vscode-icons,catppuccin,lucide"

# what is in a set / who owns the licence
curl -s "https://api.iconify.design/collections?prefixes=circle-flags,simple-icons"

# fetch the SVG itself
curl -s "https://api.iconify.design/circle-flags:fi.svg" -o public/flags/fi.svg

Browse visually at https://icon-sets.iconify.design when the user should choose. The collections response carries each set's licence — nearly all of them are permissive; Twemoji is CC BY 4.0 and needs visible attribution, which is the one that costs you something.

Iconify SVGs come out at width="1em" height="1em", and monochrome sets use currentColor — so className="size-4 text-muted-foreground" just works in Tailwind. Colour sets (vscode-icons, circle-flags, twemoji) ignore currentColor by design.

Getting them into the project

Default: write the SVG to a file and inline it. No runtime dependency, no network call, no bundle growth beyond the markup.

curl -s "https://api.iconify.design/vscode-icons:file-type-pdf2.svg" -o components/icons/pdf.svg

Only reach for a package when the project needs dozens of icons from one set:

• @iconify/react renders <Icon icon="circle-flags:fi" /> but fetches from the Iconify API at runtime — an external request per icon set, on every visitor. Do not ship that to production without saying so; pair it with @iconify-json/<prefix> offline data, or skip it.
• unplugin-icons + @iconify-json/<prefix> compiles icons in at build time. This is the right choice for a bundler-based project pulling in a whole set.

svgl — brand logos

Still the best source for product and company logos in colour, with light/dark variants.

bunx --bun shadcn@latest add https://svgl.app/r/<name>.json     # per icon
bunx --bun shadcn@latest add @svgl/<name>                       # if components.json has the @svgl registry

Several names in one command, space-separated. components.json must exist — if it does not, stop and tell the user to run bunx --bun shadcn@latest init first.

Resolve the exact name before installing:

• https://api.svgl.app?search=<query> — search
• https://api.svgl.app/categories then https://api.svgl.app/category/<category> — browse
• https://api.svgl.app/svg/<name>.svg — raw markup

svgl is software and brand logos only. Its categories are Software, Framework, AI, Library, Payment, Design and similar — there are no flags, no file types, no UI glyphs. ?search=finland returns SVG not found, and that is expected, not a bug: switch to Iconify rather than retrying svgl with a different phrasing.

Docs: https://svgl.app/docs/shadcn-ui

Making a borrowed icon fit

A single icon from a foreign family is the most common tell of pasted-in work. Match, in this order:

1. Stroke vs fill — do not drop a filled icon into an outline set. Most Iconify sets ship both (teenyicons:pdf-outline / teenyicons:pdf-solid, mingcute:pdf-line / mingcute:pdf-fill); take the variant that matches.
2. Stroke width and grid — Lucide is 24px grid, 2px stroke. Tabler and Hugeicons sit close enough to pass; Material and Carbon do not, they read thinner and boxier.
3. Colour — a mono icon inherits currentColor; a colour icon is a logo-like object and needs the same treatment as a logo (own size, own alignment, not tinted).
4. Optical size — colour file-type icons carry their own padding and look smaller at the same box; bump one step (size-5 against a row of size-4) and check by eye.

When mixing is unavoidable, mix by category, not per icon: all flags from one flag set, all file types from one file-type set, all UI glyphs from the project library.

Give every icon an accessible name or hide it. An icon-only button is unlabelled to a screen reader unless you add aria-label on the button — the SVG's own title does not substitute. An icon sitting next to text is decorative and repeats what the text already says: aria-hidden="true". Icon component libraries do not do this for you; inlined raw SVG certainly does not.

Flags specifically

• Never use emoji flags (🇫🇮) when Windows is in the audience — Segoe UI Emoji ships no flag glyphs, so they render as two letters (FI). They look fine on macOS and iOS, which is exactly why this ships broken.
• circle-flags for avatar-style circles, flagpack for rounded rectangles with a border, flag (flag-icons) for plain rectangles. Pick one and stay in it.
• Do not search for the country name — ?query=finland returns only emoji sets (twemoji:flag-finland, openmoji:…), never the real flag sets, because those are indexed by ISO code. Construct the id directly from ISO 3166-1 alpha-2, lowercase: circle-flags:fi, flagpack:se. flag needs an explicit ratio suffix — flag:fi-4x3 or flag:fi-1x1; bare flag:fi is a 404.
• Language flags are politically loaded — for a language switcher prefer the language name over a flag.

JSX conversion

Inlining raw SVG into JSX: stroke-width → strokeWidth, class → className, style strings → objects, <style> block rules inlined onto elements.

Rename every id per mark. Iconify serves the same mask id to every icon in a set — circle-flags:fi and circle-flags:se both arrive as <mask id="SVGuywqVbel">. Inline both into one language switcher and the second mask wins for both flags. Suffix them (SVGmask-fi, SVGmask-se) and update the matching mask="url(#…)" reference. Same trap with gradients in colour logos.

When nothing is found — svgrepo, flaticon

Both come up in searches and neither can be used by an agent:

• svgrepo.com returns HTTP 429 to programmatic requests, browser user-agent or not. No public API.
• flaticon.com returns 403. Its Freepik API needs a paid key, and the free tier requires visible attribution in the shipped product.

If the user wants an icon from one of these, they must download it in the browser themselves. Ask them to drop the .svg file in the project and say where; do not attempt scraping workarounds. Before using it, check the per-icon licence — svgrepo mixes CC0, MIT, CC BY and non-commercial packs on the same site, and flaticon's free tier is attribution-required. That mixed licensing plus mixed drawing style is the reason to treat both as a last resort rather than a first stop.

Better fallbacks before giving up on Iconify: search a synonym (document for file, invoice for receipt), search unprefixed to see every set, or browse the nearest category at icon-sets.iconify.design. 200k icons is usually enough.

Local organisations, universities and public bodies are in no icon set at all — a regional university, a national research centre or a municipality returns nothing from svgl or Iconify, and that is the expected answer, not a failed search. Ask the user for the official asset, or use a lettermark in a circle. Never invent a logo for a real organisation.