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

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; check attribution requirements for each selected set (including Twemoji).

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.

Register the svgl registry once in components.json, then add logos by name through the @svgl namespace, as svgl's docs show:

// components.json
{ "registries": { "@svgl": "https://svgl.app/r/{name}.json" } }

bunx --bun shadcn@latest add @svgl/<name>     # 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

<name> is the lowercased title (OpenAI → openai). search matches brand names only, so a concept ("LLM logos", "databases") goes through categories: show the candidates and install the ones the user confirms. Take the category spelling from /categories — AI resolves only in uppercase (/category/ai is a 404). Each entry's route is either a URL or a {light, dark} pair, and some entries carry a separate wordmark; pick the variant that suits the surface the logo lands on.

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.

Ensure inline SVG IDs are unique per rendered instance. Repeated masks or gradients can reference the wrong element. Use a stable instance prefix (such as React useId) and update every url(#...)/href reference; a brand-only suffix still collides when the same icon renders twice.

Other sources

If Iconify and svgl lack the asset, use the organization's official brand assets or another icon catalog. Availability, authentication and download rules change: inspect the current site and respect access restrictions. Check the license of the specific asset rather than assuming every icon in a catalog shares one.

Use an available browser when normal browsing is needed. If downloading needs the user's account or manual interaction, ask for the official asset.

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 organizations may be absent from icon catalogs. Search before assuming absence. Prefer the official asset; if none is available, use an explicitly generic placeholder rather than inventing a logo for a real organization.