DEV Community: Rushan

How to add country icons to a React app

Rushan — Mon, 31 Aug 2026 10:09:16 +0000

Geography is a blind spot in most icon libraries. They give you arrows and carets, not the shape of Japan or the outline of the EU, and the geographic packs that exist rarely fit a modern React bundle. GeoIcons does: 799 country, area, and subdivision icons, each its own named export. Adding one to a React app takes three steps: install the package, import the icon by its ISO code, and render it:

npm i @geoicons/react

import { UnitedStates, France, Japan } from '@geoicons/react/countries';

export default function App() {
  return (
    <>
      <UnitedStates size={40} aria-label="United States" />
      <France size={40} aria-label="France" />
      <Japan size={40} aria-label="Japan" />
    </>
  );
}

That is the whole path. Below: sizing, color, accessibility, and choosing an icon when you only know the country at runtime.

Step 1: Install the React package

Add the package to your project:

npm i @geoicons/react

It has no runtime dependencies beyond React and ships as ES modules, so your bundler can tree-shake it. Tree-shaking is dead-code elimination: the bundler reads your static import statements at build time, keeps only the icons you name, and drops the rest. See how it keeps the bundle small.

Step 2: Import by ISO code

Each country is a named export keyed to its ISO 3166 alpha-2 code, PascalCased. If you know the code, you know the import name, so autocomplete does most of the work:

import { UnitedStates, France, Japan, Germany, Brazil } from '@geoicons/react/countries';

Us is the United States, Fr is France, De is Germany, Br is Brazil. Importing from the /countries subpath keeps the module graph tight: you reach into the countries entry point instead of a root barrel that touches every category.

Step 3: Render and style

Each import is a plain React component. Drop it into your JSX and control it with props:

// Size in pixels, color through currentColor, weight through strokeWidth
<Germany size={40} />
<Germany size={40} stroke="#2563eb" />
<Germany size={40} strokeWidth={1.5} />
<Germany size={40} fill="currentColor" />

Every icon takes the same props:

Prop	What it does
`size`	Width and height in pixels (number or string).
`stroke`	Outline color. Defaults to `currentColor`.
`strokeWidth`	Outline thickness.
`fill`	Fill color. Set to `currentColor` for a solid icon.
`aria-label`	Accessible name. Omit for a decorative icon.

The same four, live:

Color comes from currentColor by default, so an icon follows the text color of whatever wraps it. Put one in a dark navbar and it turns light; put it on a colored button and it matches, with no per-icon color prop to thread through your tree.

Make it accessible

An icon is decorative until you give it a name. If the icon repeats a label that is already in the text, leave it decorative so screen readers skip it:

<li><UnitedStates aria-hidden="true" /> United States</li>

If the icon is the only thing conveying the country, give it an aria-label so assistive tech can announce it:

<button aria-label="Select United States">
  <UnitedStates aria-hidden="true" />
</button>

Under the hood each icon namespaces its <title> id with React's useId(), so rendering the same country twice on one page never produces duplicate ids.

How do I render a country icon at runtime?

A country picker or a data table often knows the country only as a string at render time. We left GeoIcons without an <Icon name="us" /> lookup on purpose, because a string API forces the library to keep every icon. Build your own small map instead, listing only the countries you import:

import { UnitedStates, France, Japan } from '@geoicons/react/countries';

// You own this map, so it holds only the three icons you imported.
const byCode = { us: UnitedStates, fr: France, jp: Japan } as const;

export function CountryIcon({ code }: { code: keyof typeof byCode }) {
  const Icon = byCode[code];
  return <Icon aria-hidden="true" />;
}

The bundler still sees three static imports at the top and prunes the other 419. You get a runtime lookup where you need one, without dragging in the whole catalog. For why the string-prop API breaks this, see why an icon library doesn't have to bloat your bundle.

Beyond countries: areas

The same import pattern covers 167 area icons: regions, continents, landforms, and groupings like the European Union. Areas use a PascalCase slug rather than an ISO code:

import { EuropeanUnion } from '@geoicons/react/areas';

<EuropeanUnion aria-label="European Union" />

FAQ

How do I add a country icon to a React app?

Install @geoicons/react, import the country by its ISO 3166 alpha-2 code in PascalCase, and render it as a component. For example, import { UnitedStates } from '@geoicons/react/countries' gives you a component you can size and color like any SVG.

How do I show an icon for a country chosen at runtime?

Import the countries you need and build a small object mapping codes to components, such as { us: UnitedStates, fr: France }. Look the component up by key at render time. This keeps the API tree-shakable because you only import the icons the map lists.

Get started

Install the package and render your first country:

npm i @geoicons/react

import { UnitedStates } from '@geoicons/react/countries';

export default function App() {
  return <UnitedStates aria-label="United States" />;
}

The full prop and import reference lives in the GeoIcons API reference, or browse all 799 icons to find the ones you need. New to the library? Start with the launch post.

SVG icons in React Server Components: what ships to the client

Rushan — Mon, 31 Aug 2026 10:07:54 +0000

The App Router flipped the default. Every component you write is a Server Component until something opts it out, and one 'use client' at the top of a file opts out everything below it. That makes a question worth asking before you add an icon library: does importing a single icon pull your page into a client tree?

For a lot of libraries the answer is yes. Nothing breaks when it happens, the page still renders, and you start shipping JavaScript for a static drawing.

GeoIcons icon components carry no 'use client' directive, so they render on the server and arrive as plain markup. Checking any library for this takes one search. Setting it up and confirming the result takes four steps.

// app/page.tsx (no 'use client' anywhere)
import { UnitedStates, France, Japan } from '@geoicons/react/countries';

export default function Page() {
  return (
    <p className="flex items-center gap-4">
      <UnitedStates size={40} aria-label="United States" />
      <France size={40} aria-label="France" />
      <Japan size={40} aria-label="Japan" />
    </p>
  );
}

That page is a Server Component. Next.js generates the SVG markup at build time and serves it as HTML, so no icon code runs in the browser. The route still loads React itself, and the RSC payload repeats the same path data further down the document, which matters when you go counting tags in Step 4.

Step 1: Find out whether your icon library is a Client Component

The directive has to be the first statement in a module, so you can settle this with one search over the installed package:

grep -rl "^['\"]use client['\"]" node_modules/@geoicons/react/

For GeoIcons that returns a single file, dist/_license.js, which is the license provider. None of the icon modules appear, because none of them declare the directive.

The ^ anchor earns its place. A directive only counts as the first statement in a module, and the GeoIcons icon source happens to mention use client inside a comment explaining why it avoids one. Drop the anchor and the search matches all 799 icon files while telling you nothing.

Run the same search against your current icon library. If every icon file comes back, importing one icon marks that module as a client boundary, and every component you render underneath it becomes client code too.

You can also open the file. A GeoIcons country component is short enough to read at a glance:

// node_modules/@geoicons/react/countries/base/Nz.tsx (abridged)
import { useId } from 'react';
import type { SVGProps } from 'react';
import { noteIconRender } from '@geoicons/core';

interface Props extends SVGProps<SVGSVGElement> {
  size?: number | string;
  strokeWidth?: number;
}

export const Nz = ({ size = 24, strokeWidth = 1, 'aria-label': ariaLabel, role, ...props }: Props) => {
  const uid = useId();
  noteIconRender();
  return (
    <svg
      viewBox="0 0 24 24"
      width={size}
      height={size}
      stroke="currentColor"
      strokeWidth={strokeWidth}
      fill="none"
      role={ariaLabel ? (role ?? 'img') : role}
      aria-labelledby={ariaLabel ? `${uid}-title` : undefined}
      aria-hidden={ariaLabel ? undefined : true}
      {...props}
    >
      {ariaLabel && <title id={`${uid}-title`}>{ariaLabel}</title>}
      <path d="M7.646 22.656 4.694 21.39a.5.5 0 0 1-.132-.836l5.414-4.75…" />
    </svg>
  );
};

Files are named by ISO alpha-2 code, and the barrel re-exports each one under its full country name as well, which is why you import NewZealand and read Nz.tsx.

Everything in there runs on the server. useId derives an identifier from the component's position in the render tree, which is why it works during server rendering. The icon spends it twice, as the <title> element's id and as the aria-labelledby value on the <svg>, and that pair is what lets a screen reader read the label. Pass no aria-label and the icon sets aria-hidden on itself instead, so a decorative icon stays out of the accessibility tree without you asking. Making SVG icons screen-reader accessible goes further into that behavior.

The noteIconRender() call is a license compliance nudge. GeoIcons writes it as a plain guarded function so it does not need useEffect, because reaching for an effect there would have forced the directive onto all 799 icons.

Step 2: Render icons directly in a Server Component

Once you know the icons are server-safe, import and render them:

// app/countries/page.tsx
import { UnitedStates, Germany, Japan } from '@geoicons/react/countries';

const rows = [
  { Icon: UnitedStates, name: 'United States' },
  { Icon: Germany, name: 'Germany' },
  { Icon: Japan, name: 'Japan' },
];

export default function CountriesPage() {
  return (
    <ul className="divide-y">
      {rows.map(({ Icon, name }) => (
        <li key={name} className="flex items-center gap-3 px-3 py-2">
          <Icon size={24} aria-hidden="true" />
          <span>{name}</span>
        </li>
      ))}
    </ul>
  );
}

The explicit aria-hidden there is belt and braces. Each row already names its country in text, and an icon with no aria-label hides itself, so you could leave it off and get the same result.

Passing components around in an array works here because the page renders on the server and the array never reaches the browser. The icons still tree-shake, because each one is its own named export and the bundler can see which three you referenced. Why an icon library doesn't have to bloat your bundle covers that mechanism.

Icons take their stroke color from CSS through currentColor, so a row in a dark panel gets a light icon without a color prop.

Step 3: Keep the provider at a client boundary

IconProvider is the exception. It reads a license key, verifies it, and stores the result in context. That takes state and effects, so it declares 'use client'. Only that one module is client code, and the icons never read its context to render.

Put it once in the root layout:

// app/layout.tsx
import { IconProvider } from '@geoicons/react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <IconProvider licenseKey={process.env.NEXT_PUBLIC_GEOICONS_KEY}>
          {children}
        </IconProvider>
      </body>
    </html>
  );
}

A Client Component can render Server Components handed to it as children, so wrapping the tree this way leaves your pages on the server.

If your project is open source under GPLv3, pass the GPL_DECLARATION constant instead of a key. @geoicons/react re-exports it, so you can import it alongside the provider. If you are still evaluating, leave the provider out. Icons render normally either way, and the commercial license setup has the rest.

Step 4: Verify what reached the browser

Do not take the setup on trust. Build the app and read the HTML you serve:

npx next build && npx next start
curl -s http://localhost:3000/countries | grep -o "<svg" | wc -l

Use grep -o here rather than grep -c. Next.js emits its HTML as a handful of very long lines, and -c counts matching lines, so it reports 1 however many icons the page holds. Expect each icon to turn up twice in the count, once in the markup and once in the RSC payload.

Seeing real <path d="M…"> data in that response tells you the server drew the icon. A client-rendered library will still show markup here thanks to SSR, so settle the question in the build output instead. Take a path string you know belongs to an icon and look for it in the client chunks:

grep -rl "M7.646 22.656" .next/static/chunks/ || echo "not in any client chunk"

Nothing found means nothing shipped. A hit does not prove the opposite. It means something in your app renders that icon inside a client boundary, which is a decision you made rather than one the library forced on you. Reading the network tab is the less decisive move, because Next.js shares chunks across routes and one library's cost rarely separates out cleanly.

This site is the working example, and it shows both sides. The related-icons grid at the foot of any icon page is a plain Server Component rendering icons directly, and it arrives in the prerendered HTML with full path data. Run the chunk search against the site and you will still find country paths, because the studio panel higher up the same page is a Client Component that renders icons on demand. Read the grid as the proof rather than the whole page.

When you do need "use client"

Server rendering covers display. When an icon has to respond to a click or a hover, put that behavior in a wrapper:

'use client';

import { useState } from 'react';
import { France } from '@geoicons/react/countries';

export function SelectableCountry() {
  const [selected, setSelected] = useState(false);
  return (
    <button
      onClick={() => setSelected((s) => !s)}
      className={selected ? 'text-blue-600' : 'text-gray-500'}
    >
      <France size={32} aria-label="France" />
    </button>
  );
}

The icon did not change. It is the same component from the same import, rendering inside a client boundary this time. The icons work on both sides, so you place the boundary where your interface needs it.

Do GeoIcons work in React Server Components?

Yes. The icon components carry no 'use client' directive, so they render inside Server Components and arrive as HTML with no icon code running in the browser. Only IconProvider, the license wrapper, is a Client Component, and the icons never read its context to render.

Why can an icon component call useId and still be a Server Component?

useId derives an identifier from the component's position in the render tree rather than from state or effects, which is why it works during server rendering. The icon uses it as the title element's id and as the aria-labelledby value on the svg, which is the pair a screen reader needs to read the label you pass as aria-label.

How do I check whether my current icon library forces a client boundary?

Search the installed package for a use client directive anchored to the start of a line, for example with grep -rl over node_modules for your icon package. Anchor it: a directive only counts as the first statement in a module, and an unanchored search will also match the string inside comments. If the icon modules come back in the results, importing an icon marks that module as a client boundary and everything rendered underneath it becomes client code.

Does wrapping my app in IconProvider make every page a Client Component?

No. A Client Component can render Server Components handed to it as children, so a provider in the root layout leaves the pages beneath it on the server. Only the provider module itself is client code.

Can I use the same icon in both a Server Component and a Client Component?

Yes, and it is the same import either way. Render it on the server for display, or render it inside a component marked 'use client' when it needs a click handler, hover state, or animation.

Where this leaves you

Icons are static artwork. In an App Router app they should cost you markup and nothing more, and whether they do comes down to one directive in the library you picked.

Check for it before you install. If the icons are server-safe, render them directly, keep any provider at the root, and search the client chunks to confirm.

The full prop list lives in the React API reference, and adding country icons to a React app covers sizing, color, and accessibility from the start.

Why an icon library doesn't have to bloat your bundle

Rushan — Mon, 31 Aug 2026 10:06:44 +0000

Tree-shaking is why a GeoIcons install can hold 799 icons, the count at the time of this post and still growing, while your app ships three. When you write:

import { Us } from '@geoicons/react/countries'

your bundler includes the Us component and drops the rest. You pay for what you import, not for what the package contains.

That sentence hides a lot of moving parts. Bundlers only drop code when the library is built to let them, and icon libraries are one of the easiest places to get it wrong.

What tree-shaking does

Tree-shaking is dead-code elimination for JavaScript modules. Bundlers like webpack, Rollup, esbuild, and Vite read the static import and export statements in your code, build a graph of what actually gets used, and leave everything else out of the final bundle.

The word "static" is the load-bearing part. ES modules declare their imports at the top level with literal names, so a bundler can decide at build time which exports are reachable without running your code. Here you reach three exports:

import { Us, Fr, Jp } from '@geoicons/react/countries';

The bundler follows those edges to the Us, Fr, and Jp components, marks them as used, and never marks the other 419. Unmarked exports are unreachable, so they get pruned. Three imports in, three components in your bundle. The icons themselves render like this:

Two conditions have to hold for this to work. The library must ship real ES modules, not a single CommonJS blob, because require() is dynamic and cannot be statically analyzed. And the library must promise it has no import-time side effects, so the bundler knows that dropping an unused module changes nothing. Miss either one and the bundler plays it safe by keeping code it cannot prove is dead.

Why icon libraries are where it breaks

Icon sets are large by nature: hundreds or thousands of small components that most apps use a handful of. That makes them the highest-leverage place for tree-shaking, and also the easiest place to accidentally turn it off.

The usual culprit is a convenience API. A library exposes a single component and a string prop:

// The convenient-looking API that ships everything
import { Icon } from 'some-icons';

<Icon name="us" />
<Icon name="fr" />

That name prop has to resolve to a component at runtime, which means the library keeps a lookup table somewhere:

// Inside the library
import * as flags from './all-flags';

const registry = { us: flags.Us, fr: flags.Fr, jp: flags.Jp /* ...419 more */ };

export function Icon({ name }) {
  const Svg = registry[name];
  return <Svg />;
}

The bundler cannot know that your app only passes "us" and "fr". The value could come from a variable, a prop, or an API response. To keep the code correct, it has to retain every icon the registry can reach. You imported one component and shipped all 799.

The same failure hides in a few other shapes:

A barrel file that re-exports everything and is imported as a namespace: import * as Icons from 'some-icons'.
A dynamic member access: Icons[name], where name is not a literal.
A package published only as CommonJS, so import cannot be analyzed at all.

Each one asks the bundler a question it cannot answer at build time, and the safe answer is always "keep it."

How GeoIcons is built to stay shakable

GeoIcons has no <Icon name="..."> API and no central registry. Each icon is its own named export in an ES module, imported by a name your bundler can read literally:

import { Us, Fr, Jp } from '@geoicons/react/countries';

There is no lookup table for the bundler to get stuck on. The reference to Us is a static edge to exactly one component, so everything you never name is unreachable and gets pruned. This is also why the library has no string-keyed API: adding one would reintroduce the exact registry that breaks pruning.

The package ships ES modules and marks itself side-effect free, so bundlers are allowed to drop unused icon modules instead of keeping them just in case. Category subpaths like @geoicons/react/countries keep the graph even tighter: you reach into the countries entry point rather than a root barrel that touches every category at once.

The tradeoff is explicit imports. There is no <Icon name={dynamicValue} /> escape hatch, so a dynamic icon whose identity is known only at runtime needs you to build your own small map of just the icons you use:

import { Us, Fr, Jp } from '@geoicons/react/countries';

// You control this map, so it lists only what you import.
const byCode = { us: Us, fr: Fr, jp: Jp };

export function CountryFlag({ code }: { code: keyof typeof byCode }) {
  const Icon = byCode[code];
  return <Icon aria-hidden="true" />;
}

That map holds three components because you wrote three. The bundler still sees three static imports at the top and prunes the rest. You get a runtime lookup where you need one, without dragging in the whole catalog.

See it in your own bundle

Do not take the claim on faith. Measure it. Add a bundle analyzer and look at what actually ships.

For a Next.js app:

npm i -D @next/bundle-analyzer

// next.config.ts
import withBundleAnalyzer from '@next/bundle-analyzer';

const analyzer = withBundleAnalyzer({ enabled: process.env.ANALYZE === 'true' });
export default analyzer({ /* your config */ });

ANALYZE=true npm run build

For a Vite app, rollup-plugin-visualizer gives you the same treemap. Import three icons, build, and confirm that only three icon modules appear in the report. Then import a fourth and watch exactly one module join them. That linear growth, one module per import, is the signal that tree-shaking is working. If instead the whole icon set shows up after importing one, something in the chain (a barrel, a registry, a CommonJS build) has defeated it.

Ways to accidentally defeat it

Even with a shakable library, your own code can force the bundler to keep more than you use. The common mistakes and their fixes:

Namespace imports. import * as Icons from '@geoicons/react/countries' then Icons.Us pulls the namespace object, which references every export. Import the named members you need instead.
Dynamic access on the whole set. Icons[code] over a namespace import is the registry antipattern in your own app. Build a small explicit map of only the icons you use, as shown above.
Re-export barrels you own. A local icons.ts that re-exports everything and gets imported wholesale can undo the library's work. Import from the source subpath directly.

None of these are exotic. They creep in through a shared helper or a "cleaner" import, and a bundle analyzer catches them in one build.

Why the bytes matter

Every kilobyte of JavaScript is paid for three times. It travels over the network, it gets parsed and compiled by the engine, and it runs. Parse and compile time scales with the amount of script, and on a mid-range phone that cost is far higher than on a developer laptop. Shipping 400 icons a user never sees delays the moment the page becomes interactive, for no visible benefit.

Tree-shaking removes that tax without asking you to manage it by hand. You do not maintain a manual subset of the library or split it into micro-packages. You import the icon you need at the point you need it, and the build keeps the bundle proportional to your actual usage. A library of 799 icons costs the same as a library of 12 if you only import 12. GeoIcons is built on that principle. Browse the full set to see what you would import.

FAQ

Does importing one icon include all 799?

No. Each icon is a separate named export, so a bundler that supports tree-shaking includes only the icons you import and drops the rest. Importing one component adds one module to your bundle, and the icons you never reference never ship.

Why does an <Icon name=\

A name prop resolves to a component at runtime through a lookup table that references every icon. The bundler cannot tell which names you pass, so it keeps all of them. GeoIcons instead exposes each icon as its own import, which stays shakable.

How do I confirm tree-shaking works in my app?

Run a bundle analyzer such as @next/bundle-analyzer or rollup-plugin-visualizer, then build. Import three icons and check that only three icon modules appear in the report. Import a fourth and exactly one module should join them.

Get started

Install the package and import your first icon. Then run the analyzer and confirm the bundle only grows by what you use:

npm i @geoicons/react

import { Us } from '@geoicons/react/countries';

export default function App() {
  return <Us aria-label="United States" />;
}

The full prop and import reference lives in the docs. New to the library? Start with the launch post.

Making SVG icons screen-reader accessible: titles, aria-labels, and unique IDs

Rushan — Tue, 11 Aug 2026 13:37:39 +0000

When you build an interface, icons are the part you check with your eyes and then stop thinking about. You drop an <svg> into a button, it looks great, and you move on. A screen reader user gets a different experience: either nothing where a label belonged, or an announcement of "graphic" on an icon that should have stayed quiet.

Labeling every icon is the wrong fix, because half of them sit next to text that already says the same thing. For each icon you need to decide whether it carries meaning on its own, and then mark it accordingly. That decision has two correct outcomes and one common mistake, and once you name an icon you inherit a second problem: the <title> element needs an id, and ids must be unique on the page.

In this article we'll walk through both outcomes with real markup, see what an id collision does to a screen reader, and use GeoIcons, a premium library of geographic map-shape icons, to get both behaviors from a single prop.

Why is my SVG icon invisible to screen readers?

An <svg> element has no implicit accessible name or useful default role. The browser sees a graphic without any text to announce, so there is nothing meaningful for a screen reader to read. VoiceOver and NVDA may skip the icon entirely or announce something vague like "image" without a name.

In many cases, this is exactly what you want. If an icon appears next to the word "France", a screen reader ignoring the icon will simply read "France" once, which conveys the same single piece of information a sighted user takes from the row.

The problem comes when the icon is the only thing communicating information. If the icon is meaningful on its own, a screen reader needs a way to identify it.

So, for each icon, ask yourself: does this icon communicate information that the surrounding text does not?

The answer determines how you should mark up the SVG.

Decorative icons should say nothing

If nearby text already conveys the meaning, the icon is decorative. Mark it aria-hidden="true" so assistive technology skips it and reads the text instead.

With GeoIcons this is the default. Render an icon with no aria-label and you get a hidden graphic:

import { France } from '@geoicons/react/countries';

<span>
  <France /> France
</span>

That produces:

<svg viewBox="0 0 24 24" width="24" height="24" stroke="currentColor"
     stroke-width="1" fill="none" aria-hidden="true">
  <path stroke-linejoin="round" d="m6.356 17.388…"/>
</svg>

A screen reader reads "France" once. Without aria-hidden, some setups would announce a nameless graphic before the word, which adds noise and tells the user nothing.

Meaningful icons need an accessible name

If the icon stands alone, it needs a name. Pass aria-label and you turn a decoration into a named image:

<France aria-label="France" />

That produces:

<svg viewBox="0 0 24 24" width="24" height="24" stroke="currentColor"
     stroke-width="1" fill="none" role="img" aria-labelledby="_r_7_-title">
  <title id="_r_7_-title">France</title>
  <path stroke-linejoin="round" d="m6.356 17.388…"/>
</svg>

The _r_7_-title id looks cryptic, and that is fine. A screen reader never reads the id, it reads the text inside the <title>, so "France" is what the user hears. The id exists only to connect the two elements, which is why a generated value beats a readable one like france-title.

Three things changed together, and each one matters:

role="img" tells assistive technology to treat the SVG as a single image instead of a container of shapes. Without it, support for naming a bare <svg> has historically been uneven across screen readers, and some will still expose the graphic as a group rather than an image.
<title> is the SVG element that holds the accessible name. It is the SVG equivalent of an alt attribute, and it is not rendered visually. Browsers do surface it as a tooltip on hover, which is a small bonus rather than the point.
aria-labelledby points at the <title> by id, which is the association that gives the image its name.

You pass one prop and get all three.

Here are both treatments side by side. The first row pairs a decorative icon with a visible label, and the second row leaves the icon alone, carrying its own name:

import { France, Japan } from '@geoicons/react/countries';

// Decorative: the visible label names the row, so the icon stays hidden.
<span className="flex items-center gap-2">
  <France size={32} /> <span>France</span>
</span>

// Meaningful: nothing else names it, so the icon carries the name.
<Japan size={32} aria-label="Japan" />

Why does the `<title>` need a unique id?

aria-labelledby names an icon by pointing at an id, and ids must be unique in a document. If two icons on the same page both render <title id="fr-title">, the browser resolves that reference to whichever one comes first. Every icon sharing the id then announces the first icon's name.

A country list, a filter bar, and a footer will happily render the same icon three times. With a hardcoded id, two of those three announce the wrong name. Duplicate ids are also invalid HTML, so validators, linters, and some testing tools flag the problem before a user hits it.

Every GeoIcon calls React's useId() and namespaces its <title> id with the result:

const uid = useId();
// …
aria-labelledby={ariaLabel ? `${uid}-title` : undefined}
// …
{ariaLabel && <title id={`${uid}-title`}>{ariaLabel}</title>}

useId() returns a value that is unique per component instance and stable between the server render and the client hydration, so the ids match on both sides and React does not warn about a mismatch. The exact string is a React implementation detail. React 19 generates ids like _r_7_ in the browser and _R_2_ when the markup comes from the server, and React 18 produced :r7: instead, so never write a selector or a test that depends on the shape. Render the same icon twice and you get two different ids:

<France aria-label="France" />
<France aria-label="France, selected" />

<svg role="img" aria-labelledby="_r_7_-title">
  <title id="_r_7_-title">France</title>
</svg>
<svg role="img" aria-labelledby="_r_8_-title">
  <title id="_r_8_-title">France, selected</title>
</svg>

The two IDs are different, so each <title> stays linked to its own icon. A screen reader announces "France" for the first one and "France, selected" for the second. This continues to work correctly no matter how many copies of the icon appear on the page.

Icon-only buttons: label the control, hide the icon

The most common accessibility bug in icon work is doubling up the name. You put an aria-label on the button because it has no visible text, then put another one on the icon inside it, and a screen reader user hears the name twice.

Label the button, and leave the icon decorative:

<button aria-label="Filter by France">
  <France />
</button>

The button announces "Filter by France, button". The icon inside stays aria-hidden="true" and adds nothing.

The same rule covers links, menu items, and toolbar controls. Whichever element the user clicks or perceives as one unit is the element that carries the name, and everything inside it is decoration.

// Link with visible text: the text is the name, the icon is decorative.
<a href="/icons/de">
  <Germany /> Germany
</a>

// Standalone status indicator: nothing else names it, so the icon does.
<Japan aria-label="Shipping from Japan" />

The same rules in Vue, Angular, and vanilla JS

All four GeoIcons packages behave the same way here, since the rules live in the rendered markup rather than in any one framework. No aria-label gives you a hidden icon, and an aria-label gives you role="img", a <title>, and a unique id. The Vue and vanilla packages also leave your aria-label on the <svg> next to the generated <title>, which changes nothing for the user, because aria-labelledby wins the name computation.

<script setup>
import { France } from '@geoicons/vue/countries';
</script>

<template>
  <!-- Decorative -->
  <France /> France

  <!-- Meaningful -->
  <France aria-label="France" />
</template>

Vue uses its own useId() on Vue 3.5 and later, and falls back to a per-instance uid on earlier versions, so the id stays unique either way.

Angular follows the same contract. Import the icon into your standalone component, then use its element selector in the template:

import { France } from '@geoicons/angular/countries';
// @Component({ standalone: true, imports: [France], template: `…` })

<!-- Decorative -->
<geoicon-fr></geoicon-fr> France

<!-- Meaningful -->
<geoicon-fr aria-label="France"></geoicon-fr>

Angular has no useId(), so the package supplies its own GeoIconIdService. It is provided in root, so Angular Universal creates a fresh instance per server-side request and the counter restarts at zero for every render. The server and client id sequences line up, and hydration produces no mismatch warnings.

import { France } from '@geoicons/vanilla/countries';

// Decorative
document.body.append(Fr());

// Meaningful
document.body.append(Fr({ 'aria-label': 'France' }));

The vanilla factory keeps a module-level counter and builds the <title> element with createElementNS, then inserts it as the first child of the <svg>.

How do I verify it works?

Read the accessibility tree rather than the DOM. The DOM shows you which attributes you wrote, while the accessibility tree shows you the role and the name a screen reader will receive.

Chrome DevTools: open the Elements panel, select the icon, and look at the Accessibility pane. A decorative icon shows as ignored, with aria-hidden given as the reason. A meaningful icon shows the role image and the name you passed.
A real screen reader: turn on VoiceOver with Cmd+F5 on macOS, or NVDA on Windows, and tab through the component. Your icon buttons should announce one name each, not two, and not none.
Automated checks: axe DevTools flags a duplicate id that ARIA points at, through its duplicate-id-aria rule, and both axe and Lighthouse flag a button with no accessible name. Axe's general duplicate-id rule is deprecated and off by default, so an HTML validator remains the tool that catches every collision. Neither one can tell you that "France" was the wrong name for an icon that meant "shipping origin", so keep reading your labels yourself.

FAQ

Should I use aria-label or a element on an SVG icon? </h3> Use a <title> element referenced by aria-labelledby, which is what GeoIcons builds for you. You pass an aria-label prop, and the React component uses that string as the <title> text and renders role='img' plus aria-labelledby instead of an aria-label attribute. Passing aria-label alone on a bare <svg> has had uneven screen reader support historically, so the titled reference is the reliable pattern. <h3> <a name="do-decorative-icons-need-ariahidden-if-they-have-no-label" href="#do-decorative-icons-need-ariahidden-if-they-have-no-label" class="anchor"> </a> Do decorative icons need aria-hidden if they have no label? </h3> Yes, and GeoIcons adds it automatically. An unlabeled <svg> can still be announced as a nameless graphic by some screen readers, which adds noise without adding meaning. Setting aria-hidden='true' removes the icon from the accessibility tree entirely, so the nearby text is read once and nothing else. <h3> <a name="what-happens-if-two-svg-icons-share-the-same-id" href="#what-happens-if-two-svg-icons-share-the-same-id" class="anchor"> </a> What happens if two SVG icons share the same <title> id? </h3> The browser resolves aria-labelledby to the first element with that id, so every later icon announces the first icon's name. It is also invalid HTML. GeoIcons avoids this by generating a unique id per instance with React's useId (or the equivalent in the Vue, Angular, and vanilla packages), so the same icon rendered many times on one page never collides. <h2> <a name="get-started" href="#get-started" class="anchor"> </a> Get started </h2> Install the package and label only the icons that carry meaning: <div class="highlight"><pre class="highlight shell"><code>npm i <a class="mentioned-user" href="https://dev.to/geoicons">@geoicons</a>/react </code></pre></div> <div class="highlight"><pre class="highlight tsx"><code>import { France, Japan } from '<a class="mentioned-user" href="https://dev.to/geoicons">@geoicons</a>/react/countries'; export default function App() { return ( <ul> {/* Decorative: the text names the row. /} <li><France /> France</li> {/ Meaningful: the icon is on its own. */} <li><Japan aria-label="Japan" /></li> </ul> ); } </code></pre></div> For the full accessibility contract of every icon, see <a href="https://geoicons.io/docs/accessibility">the accessibility docs</a>, and for every prop each icon accepts, see <a href="https://geoicons.io/docs/api">the GeoIcons API reference</a>. New here? Start with <a href="https://geoicons.io/blog/add-country-icons-react">adding your first country icon</a>, see how <a href="https://geoicons.io/blog/dark-mode-icons">currentColor keeps icons readable in dark mode</a>, or <a href="https://geoicons.io/icons/countries">browse all 799 icons</a>.

ISO 3166-1 Alpha-2 Country Codes: A Developer's Guide

Rushan — Wed, 29 Jul 2026 03:46:53 +0000

Any application that ships across borders needs a way to name a country. You reach for a two-letter code, write US, JP, DE, and move on.

Then a support ticket arrives. A user in Belfast picked "United Kingdom" and your shipping API rejected UK. Someone in Pristina found no option at all. Your analytics dashboard shows a country called AN that dissolved in 2010.

These bugs share one root: ISO 3166-1 alpha-2 carries more rules than its two characters suggest. Let's walk through the parts that break real applications, and how to model country data so the next revision of the standard does not break yours.

What alpha-2 covers

ISO 3166 splits into three parts. Part 1 names countries and their dependent territories. Part 2 names subdivisions inside them. Part 3 records codes that fell out of use.

Part 1 gives you three code sets for the same entity:

Format	Japan	Notes
Alpha-2	`JP`	Two letters. Used by ccTLDs, BCP 47 language tags, payment APIs.
Alpha-3	`JPN`	Three letters. Easier to read on its own.
Numeric-3	`392`	Digits from UN M49. Script-independent, survives alphabet changes.

Alpha-2 is the set you meet most often. Two characters fit anywhere, and the Internet Assigned Numbers Authority (IANA) draws the country-code top-level domains straight from the alpha-2 list, which puts these codes in front of everyone who ever registered a domain. That reach explains the misuse.

Five kinds of code

The 249 official codes get the attention. Most bugs come from the reserved ranges.

Status	Examples	What you do with them
Officially assigned	`US`, `JP`, `DE`	Use these. 249 of them.
Exceptionally reserved	`EU`, `UK`, `UN`, `AC`	Reserved for a specific requester. Never repurpose them.
Transitionally reserved	`AN`, `CS`, `YU`, `BU`	Retired countries. Keep them readable in old records, block them in new input.
Indeterminately reserved	`RI`, `WG`, `FL`	Vehicle registration codes that clash with ISO. Ignore.
User-assigned	`AA`, `QM`–`QZ`, `XA`–`XZ`, `ZZ`	Yours to use. ISO promises never to assign them.

That last row deserves a bookmark. When you need a code for something ISO does not cover, an internal test region or a disputed territory, take one from the user-assigned range. Inventing a code outside that range, ZQ or OJ, guarantees a collision the day ISO assigns it.

The United Kingdom is GB

This is the mistake that reaches production most often. The ISO code for the United Kingdom of Great Britain and Northern Ireland is GB.

UK exists in the standard, but only as an exceptional reservation. The reservation exists to accommodate .uk, which was already in wide use before ISO codes reached domain names, so the United Kingdom asked ISO to set the code aside rather than assign it elsewhere. It never became a country code, and a strict validator rejects it.

The confusion has an official source. The European Commission publishes country codes that match ISO with two deliberate exceptions: it writes UK for the United Kingdom and EL for Greece. If your data arrives from an EU statistical feed, normalize both before you store anything:

const EU_TO_ISO: Record<string, string> = { UK: 'GB', EL: 'GR' };

export function toIso3166(code: string): string {
  const upper = code.trim().toUpperCase();
  return EU_TO_ISO[upper] ?? upper;
}

Run every inbound code through one function like this. Patch each call site instead and the rules drift apart within a quarter.

Kosovo sits outside the standard

Kosovo has no officially assigned alpha-2 code. ISO assigns codes to entities that are UN members or appear on the UN Statistics Division's country list, and Kosovo's status blocks both routes.

In practice, XK won. The European Commission, the IMF, and SWIFT all use it, and it comes from the user-assigned XA–XZ range, so ISO will never hand it to another country. GeoIcons ships the shape as Xk for the same reason.

import { Xk } from '@geoicons/react/countries';

<Xk size={64} aria-label="Kosovo" />

If your validator checks incoming codes against a strict ISO list, XK fails and Kosovo disappears from your form. Add it to the allowlist and document why.

Codes get recycled

A retired code moves to transitionally reserved status, where ISO intends to hold it for at least 50 years before it returns to circulation. Intends, not guarantees.

CS made the round trip in ten. It belonged to Czechoslovakia until 1993, and in 2003 it came back as Serbia and Montenegro. That union dissolved in 2006, so CS sits reserved again while RS and ME carry the successor states.

The Netherlands Antilles produced a cleaner split. When AN dissolved in October 2010, three codes replaced it: CW for Curaçao, SX for Sint Maarten, and BQ for Bonaire, Sint Eustatius and Saba.

Two consequences for your schema. A country code identifies a country at a point in time, so an old row carrying AN needs a date to interpret it. And a code you resolve to a name today may resolve to a different name in a decade, which rules out caching the pair as if it were permanent.

Names change, codes hold

The code is the stable half of the pair, and the name is the half that moves.

Year	Change	Code
2013	Cape Verde becomes Cabo Verde	`CV`
2016	Czech Republic adds the short name Czechia	`CZ`
2018	Swaziland becomes Eswatini	`SZ`
2019	Macedonia becomes North Macedonia	`MK`
2022	Turkey becomes Türkiye	`TR`

Five renames in a decade, zero code changes. Store TR in your database and resolve the display name from a library you can update, such as i18n-iso-countries. Store "Turkey" as a string and you own a migration.

Search deserves the same treatment. A user who learned "Swaziland" in school will type it, so keep the old names as aliases even after the label changes.

Subdivisions live in part 2

England, Scotland, Wales, and Northern Ireland have no alpha-2 codes. They are subdivisions of GB under ISO 3166-2, written GB-ENG, GB-SCT, GB-WLS, and GB-NIR. US states follow the same pattern: California is US-CA.

Users care about this distinction more than standards bodies do. A Scottish customer filling in a shipping form wants to see Scotland. Your payment processor wants GB.

Handle both. Show the subdivision in the interface, send the country code to the API:

import { Scotland } from '@geoicons/react/countries';

const REGION = { id: 'GB-SCT', label: 'Scotland', country: 'GB' };

<button className="flex items-center gap-2" value={REGION.country} data-region={REGION.id}>
  <Scotland size={20} aria-hidden="true" />
  <span>{REGION.label}</span>
</button>

GeoIcons ships these four as England, Scotland, Wales, and NorthernIreland rather than forcing them into a code the standard does not define.

Regions have no country code at all

The European Union is not a country, so it holds EU as an exceptional reservation. ASEAN, Mercosur, and the GCC hold nothing. Neither does a shipping zone you invented last week.

Trade blocs and continents belong in a separate namespace from countries. Mixing an EU row into a table of ISO codes means every consumer of that table now needs to know which rows are real countries.

GeoIcons keeps the same separation. Countries import from @geoicons/react/countries, regions from @geoicons/react/areas:

import { UnitedKingdom, EuropeanUnion } from '@geoicons/react/areas';

<UnitedKingdom size={40} aria-label="United Kingdom" />
<EuropeanUnion size={40} aria-label="European Union" />

The United Kingdom is the one entity that does not ship as a country shape. There is no Gb export. The four constituents live in countries as England, Scotland, Wales, and NorthernIreland, and the union itself ships as an area shape, UnitedKingdom, alongside GreatBritain.

Rules for your codebase

Six habits that prevent most country-data bugs:

Store the alpha-2 code, not the name. CHAR(2) is enough. Resolve names through a library at render time.
Uppercase on the way in. The standard writes codes in uppercase. Lowercase shows up in domains and URLs, so normalize once at the boundary and compare case-insensitively.
Validate against a real list. A regex of ^[A-Z]{2}$ accepts ZQ. Check membership in the 249 official codes plus the exceptions you choose to allow.
Keep an explicit exception list. XK for Kosovo, EL and UK from EU feeds. Write the reasons in a comment next to the list.
Do not derive flag emoji from codes without a fallback. Regional indicator pairs produce nothing for UK, XK, or any retired code, and Windows renders the letters instead of a graphic for every flag. Vector map outlines dodge both problems, which we covered in map shapes versus flag emojis.
Version your reference data. Note which revision of the ISO list your snapshot came from, so a diff against next year's list takes minutes.

How GeoIcons maps to the standard

The library carries 255 country shapes. Most of them use the alpha-2 code in PascalCase as the export name, so US becomes Us and JP becomes Jp. The rest follow the edge cases described above:

UK constituents ship under their names: England, Scotland, Wales, NorthernIreland.
Kosovo ships as Xk, matching the code the financial world settled on.
The Caribbean Netherlands splits by island, since BQ covers three: BqBonaire and BqSintEustatius ship today.
Mainland variants drop distant territories for selectors that need a compact shape: FrMainland, AuMainland.

Alpha-2 is the right value to store, but it is unguessable at the import site: Bt is Bhutan, Bj is Benin. So every country also exports its full name as an alias, pointing at the same shape. Reach for whichever reads better where you write it:

import { UnitedStates } from '@geoicons/react/countries'; // same icon as `Us`
import { Bhutan, SouthKorea } from '@geoicons/react/countries';

Nothing changes about the storage advice: the alpha-2 code stays your canonical value in the database. The alias only spares you a lookup when you type the import.

Every shape is a separate named export, so importing Us and Jp pulls two icons into your bundle and leaves the other 253 behind. The alias costs nothing here either: UnitedStates and Us resolve to one component, so the bundler ships it once. Read why an icon library doesn't have to bloat your bundle for how that works.

FAQ

How many ISO 3166-1 alpha-2 codes are there?

249 codes are officially assigned to countries and dependent territories. Additional codes exist as user-assigned, exceptionally reserved, transitionally reserved, or indeterminately reserved entries, but none of those identify a current country.

Is the country code for the United Kingdom GB or UK?

GB. The code UK is exceptionally reserved because the .uk domain was already established when ISO codes reached the internet, and it is never an officially assigned country code. The European Commission uses UK in its own publications, which is why the wrong value spreads through EU data feeds.

What is Kosovo's ISO country code?

Kosovo has no officially assigned code. XK, drawn from the user-assigned XA to XZ range, is the de facto standard used by the European Commission, the IMF, and SWIFT. ISO will never assign XK to another country, so it is safe to adopt.

Should I store alpha-2 or alpha-3 codes?

Alpha-2 for most applications, since it matches ccTLDs, BCP 47 language tags, and the majority of payment and shipping APIs. Choose numeric-3 when your data outlives alphabet changes or crosses scripts, because those codes carry no Latin letters.

Do I have to import GeoIcons by ISO code?

No. Every country exports its full name as an alias next to the ISO one, so UnitedStates and Us are the same component, as are Bhutan and Bt. Import whichever reads better; both tree-shake to a single icon. The ISO code is still the value you should store in your database.

Do ISO country codes ever change?

Codes change far less often than names. Türkiye, Eswatini, and North Macedonia all renamed themselves without changing TR, SZ, or MK. Codes do get retired when a country dissolves. ISO aims to hold a retired code for at least 50 years before reassigning it, but it has broken that guideline: CS moved from Czechoslovakia to Serbia and Montenegro after only ten.

Get started

Install GeoIcons and render any country by its ISO code:

npm i @geoicons/react

import { Gr, Tr, Xk } from '@geoicons/react/countries';

export default function Balkans() {
  return (
    <div className="flex items-center gap-3 text-slate-900 dark:text-slate-100">
      <Gr size={24} aria-label="Greece" />
      <Tr size={24} aria-label="Türkiye" />
      <Xk size={24} aria-label="Kosovo" />
    </div>
  );
}

Browse the full set of 255 country shapes and 167 area shapes in the icon catalog, or read the API reference for sizing, color, and accessibility props.

Visual Alignment for Icons and Labels in Tailwind CSS

Rushan — Fri, 24 Jul 2026 10:41:29 +0000

Vector icons do not line up with text out of the box. Unlike letters, graphic paths lack a consistent baseline, ascender, or descender. If you place an icon next to a text label using browser defaults, the shape floats above or below the text baseline.

We use GeoIcons components for the examples in this post. The library includes clean, optimized map outlines for all countries and regions. Because each shape is a real geographic outline rather than a uniform square glyph, the same alignment rules you would use for any icon apply directly, and each component exposes size and className props to make them easy to apply.

You can fix this visual gap with Tailwind CSS flexbox utilities and relative sizing.

Anchor the visual centers

Use flexbox to align the icon container and the text block. A standard block layout stacks the elements. Raw inline SVG elements line up the bottom edge of the canvas with the text baseline, pushing the icon upward.

Wrap the icon and the text in a container with flex alignment:

import { Japan } from '@geoicons/react/countries';

export default function CountryBadge() {
  return (
    <div className="flex items-center gap-2">
      <Japan size={20} aria-hidden="true" />
      <span>Japan</span>
    </div>
  );
}

The items-center utility aligns the vertical midpoints of both child elements. The gap-2 utility adds a consistent horizontal spacer.

Match icon size to line height

Scale the icon height to match the text line-height. Standard Tailwind body text uses the text-base class, which carries a font size of 16px and a line-height of 24px. If you set the icon height to 16px, the icon sits within a 24px vertical container, causing a vertical mismatch.

Set the icon height to match the line-height of the text:

{/* For text-base (24px line-height), use a 20px icon */}
<div className="flex items-center gap-2 text-base leading-6">
  <UnitedStates className="h-5 w-5" aria-hidden="true" />
  <span>United States</span>
</div>

{/* For text-sm (20px line-height), use a 16px icon */}
<div className="flex items-center gap-2 text-sm leading-5">
  <UnitedStates className="h-4 w-4" aria-hidden="true" />
  <span>United States</span>
</div>

Choosing an icon height smaller than the line-height leaves space for the border of the icon to sit clear of adjacent text lines.

Correct asymmetric visual weight

Every country has its own distinctive proportions. A long, narrow country like Italy or Chile sits differently within its square canvas than a compact country like France or Poland. The browser centers the bounding box of the SVG, but the visual weight of the shape can sit slightly off-center.

You can correct this offset using relative translation classes on the icon element:

import { Italy } from '@geoicons/react/countries';

export default function ItalyListRow() {
  return (
    <div className="flex items-center gap-2">
      <Italy className="h-5 w-5 translate-y-[1px]" aria-hidden="true" />
      <span>Italy</span>
    </div>
  );
}

The translate-y-px utility shifts the vector shape down by one pixel, centering the visual weight of the path relative to the uppercase characters of the text label.

Put it together: common UI patterns

The rules above (flex centering, size matched to line-height, an optional pixel nudge) carry over to real components. Here are a few patterns you will reach for most often.

Buttons

A button already sets its own line-height and padding, so lean on inline-flex items-center and let the icon inherit the button's text size. Size the icon a touch below the label so it reads as a companion to the text rather than competing with it.

import { Japan } from '@geoicons/react/countries';

export default function ShipToButton() {
  return (
    <button
      type="button"
      className="inline-flex items-center gap-2 rounded-md bg-slate-900 px-4 py-2 text-sm font-medium text-white"
    >
      <Japan className="h-4 w-4" aria-hidden="true" />
      Ship to Japan
    </button>
  );
}

The label already names the country, so the icon is decorative: keep aria-hidden="true" and let the text carry the meaning for screen readers.

List rows

Lists are where alignment matters most, because any drift repeats down the whole column. Set one icon size for the list and align every row the same way. The visual center stays locked regardless of how wide or narrow each country's outline is.

import { Italy } from '@geoicons/react/countries';
import { UnitedStates } from '@geoicons/react/countries';
import { Japan } from '@geoicons/react/countries';

const countries = [
  { code: 'US', name: 'United States', Icon: UnitedStates },
  { code: 'IT', name: 'Italy', Icon: Italy },
  { code: 'JP', name: 'Japan', Icon: Japan },
];

export default function CountryList() {
  return (
    <ul className="divide-y divide-slate-200">
      {countries.map(({ code, name, Icon }) => (
        <li key={code} className="flex items-center gap-3 py-2 text-base">
          <Icon className="h-5 w-5 shrink-0" aria-hidden="true" />
          <span>{name}</span>
        </li>
      ))}
    </ul>
  );
}

The shrink-0 utility stops the icon from squeezing when a long country name wraps, keeping the left edge of every label flush.

Inputs

For a country field, place the icon inside the input using absolute positioning and pad the text so it never overlaps the shape. Vertical centering comes from top-1/2 plus a -translate-y-1/2 nudge, which keeps the icon centered no matter the input height.

import { UnitedStates } from '@geoicons/react/countries';

export default function CountryInput() {
  return (
    <div className="relative">
      <UnitedStates
        className="pointer-events-none absolute left-3 top-1/2 h-5 w-5 -translate-y-1/2"
        aria-hidden="true"
      />
      <input
        type="text"
        defaultValue="United States"
        className="w-full rounded-md border border-slate-300 py-2 pl-10 pr-3 text-base"
      />
    </div>
  );
}

The pointer-events-none utility lets clicks pass through the icon to the field, so the input stays fully focusable and editable.

Inline with text

Inside a sentence, set the icon's width and height in em units so they track the surrounding font size automatically, and add a small translate-y to sit it on the text baseline. The h-[1em] w-[1em] classes are still the usual width and height, just expressed relative to the text instead of a fixed pixel value.

import { Italy } from '@geoicons/react/countries';

export default function InlineMention() {
  return (
    <p className="text-base">
      Our team just opened a new office in{' '}
      <span className="inline-flex items-center gap-1 font-medium">
        <Italy className="h-[1em] w-[1em] translate-y-px" aria-hidden="true" />
        Italy
      </span>
      .
    </p>
  );
}

Because the width and height are 1em, the icon scales with the text: bump the paragraph to text-lg and the icon grows with it, no extra classes needed.

Every pattern here reuses the same three ideas, so once the alignment feels right in one component it stays right everywhere you drop an icon.

Why Map Shape Icons Beat Flag Emojis for Country Selectors

Rushan — Fri, 17 Jul 2026 10:53:30 +0000

Many developers use system emoji flags for country selectors. Pasting a flag emoji into code requires no library, adds zero bytes to a bundle, and inherits standard text styles.

This approach carries design and technical limits. Emojis render in different ways across operating systems, and flags can clutter a modern user interface. Vector map shapes offer a clean, reliable alternative.

The Windows rendering gap

Microsoft Windows does not display flag emojis. Instead of the flag graphic, Windows displays the two-letter ISO country code inside a thin border.

If your interface relies on flags to guide users, Windows visitors see a list of text codes. A user searching for Japan sees "JP". A user looking for the United Kingdom sees "GB". This behavior breaks visual layouts and slows down country selection.

Using SVG map outlines solves this platform gap. SVGs use vector paths to draw the country boundaries. Every browser on Windows displays the shape as intended.

Design consistency: Flags versus map shapes

Flags contain complex designs, bright colors, and varied patterns. When you place multiple flags in a list, the visual noise competes for the user's attention. Emojis also fail to adapt to your application's theme. A bright red, white, and blue flag emoji stands out on a dark-themed dashboard, breaking your color palette.

SVG map shapes provide design control. Because they draw outlines with stroke="currentColor", they inherit the CSS color of their container. When your application switches to dark mode, the map shapes transition with your text.

With GeoIcons, every country shape fits a uniform grid, creating a balanced layout.

Beyond ISO countries: Mapping markets and regions

Flag emojis represent sovereign nations and specific territories. This mapping fails when your application needs to represent regional markets or continents.

If your business serves the European Union, or groups shipping zones by West Africa or Asia-Pacific, a single flag emoji cannot represent the region. You end up mixing flags with text labels, creating an inconsistent list.

SVG map shapes resolve this limit. You can represent geographical regions, continental groupings, or custom trade zones using the same visual style as country shapes. GeoIcons contains 167 area shapes alongside standard countries, letting you build cohesive region selectors.

Scaling and positioning

Emojis are text characters, meaning their size and position depend on system font files. Aligning a flag emoji with text requires custom margins that vary by browser. Emojis also lose clarity when scaled, showing pixelation on high-resolution screens.

SVG elements live in the DOM as vector graphics. You set their width and height in pixels, and they scale without losing sharpness. You can align them using flexbox or CSS grid like any other UI component.

import { UnitedStates, England, Japan } from '@geoicons/react/countries';

export function CountryList() {
  return (
    <div className="flex items-center gap-4 text-slate-900 dark:text-slate-100">
      <UnitedStates size={24} aria-label="United States" />
      <England size={24} aria-label="England" />
      <Japan size={24} aria-label="Japan" />
    </div>
  );
}

Making the transition

Replacing flags with map shapes improves both the design and the reliability of your interface. By switching to SVGs, you guarantee that every user sees the same interface, no matter their device.

FAQ

Why do flag emojis not show up on Windows?

Windows does not include flag designs in its system emoji font. The operating system renders the two-letter ISO code instead. To show a geographic graphic on Windows, you must use an image file or an SVG icon.

How do SVG country outlines improve accessibility?

Emojis rely on the system screen reader to announce their meaning, which varies by platform. SVG icons let you define custom aria-label attributes and title tags in the code, providing a predictable experience for screen reader users.

Does switching to SVG shapes increase my bundle size?

This occurs if you load the entire library. When you use named exports from a library like GeoIcons, your bundler removes the icons you do not import, keeping your bundle small.

Get started

Add GeoIcons to your project and replace your text emojis with consistent SVG elements:

npm i @geoicons/react

import { UnitedStates } from '@geoicons/react/countries';

export default function Selector() {
  return (
    <button className="flex items-center gap-2">
      <UnitedStates size={20} aria-label="United States" />
      <span>United States</span>
    </button>
  );
}

For styling options and import paths, consult the API reference. To understand how GeoIcons maintains small bundles, read our article on tree-shaking performance.

Make your icons follow dark mode automatically with currentColor

Rushan — Thu, 16 Jul 2026 15:00:00 +0000

Most icon sets bake a color into the SVG. The fill is set to #111 in the file, so the icon looks right on a white page and then disappears the moment you switch to a dark background. You end up passing a color prop to every icon, or writing theme-specific overrides for each one.

GeoIcons take the other approach. Each icon draws its outline with stroke="currentColor", so it reads the CSS color of whatever wraps it. Set the text color for your light and dark themes once, and every icon on the page follows along:

import { Japan, France, Germany } from '@geoicons/react/countries';
import { EuropeanUnion } from '@geoicons/react/areas';

// None of these set a color. They all inherit the text color of the wrapper.
<div className="text-slate-900 dark:text-slate-100">
  <Japan size={40} /> 
  <France size={40} /> 
  <Germany size={40} /> 
  <EuropeanUnion size={40} />
</div>

What does currentColor do?

currentColor is a CSS keyword that means "the computed value of this element's color property." A GeoIcon sets stroke="currentColor" on its <svg>, so the outline paints in whatever color the icon inherits. Change the color anywhere up the tree, and the stroke changes with it.

That is the whole mechanism. There is no theme context, no provider, no color prop threaded through your components. The icon is a piece of text as far as color is concerned.

<p style={{ color: '#e11d48' }}>
  <France aria-hidden="true" /> France
</p>

The <France /> outline turns rose because it inherits color: #e11d48 from the paragraph.

Why do hardcoded icon colors break in dark mode?

An icon with a fixed fill="#111827" in its SVG cannot respond to a theme. Dark mode flips your background to near-black, and the icon stays near-black on top of it, so it vanishes. Your only fixes are to override the fill per theme or swap in a second icon file for dark backgrounds.

currentColor removes that work. The icon holds no color, so there is nothing to override. You style the container, and the icon inherits the result.

How do I switch icons for a dark theme?

Pick the color for each theme and let the icon inherit it. If you toggle dark mode with a class on <html> (the common pattern in Tailwind and most CSS setups), scope the color to that class:

:root {
  color: #0f172a; /* slate-900 for light mode */
}

.dark {
  color: #e2e8f0; /* slate-200 for dark mode */
}

Every icon under <html class="dark"> now paints in #e2e8f0. With Tailwind you can skip the CSS and put the two colors on the icon itself:

<Germany
  className="text-slate-900 dark:text-slate-100"
  aria-label="Germany"
/>

The text-* utilities set color, and the icon's currentColor stroke picks it up. One element, both themes.

How do I follow the system setting instead?

Read the operating system preference with the prefers-color-scheme media query and set color from it. This needs no JavaScript and no class toggle:

:root {
  color: #0f172a;
}

@media (prefers-color-scheme: dark) {
  :root {
    color: #e2e8f0;
  }
}

Now the icons track the user's system theme. Someone on a phone that flips to dark at sunset sees the lighter outline without any work from you.

Can I recolor an icon on hover?

Yes. Because the icon follows color, any state that changes color also changes the icon. A hover on the button recolors the outline inside it:

.icon-button {
  color: #64748b; /* slate-500 at rest */
}

.icon-button:hover {
  color: #2563eb; /* blue-600 on hover */
}

<button className="icon-button" aria-label="Filter by France">
  <France aria-hidden="true" />
</button>

The same idea covers focus rings and disabled states. You style the button, and the icon comes along.

Outline or solid: stroke versus fill

GeoIcons render as outlines. The stroke is currentColor and the fill is none, which is why theming runs through the stroke. If you want a solid glyph, set fill yourself and keep it on currentColor so it still follows the theme:

<France fill="currentColor" stroke="none" aria-label="France" />

Both the stroke path and a currentColor fill respect the same inherited color, so a solid icon themes exactly like an outline one.

FAQ

How do I make an icon change color in dark mode?

Set the CSS color property for your dark theme, either on a .dark class or through a prefers-color-scheme media query. GeoIcons draw with stroke='currentColor', so each icon inherits that color automatically. You do not pass a color prop to the icon itself.

Do I need a color prop on every GeoIcon?

No. Each icon borrows the CSS color of its container through currentColor. Set color once per theme and every icon follows. Pass an explicit stroke or fill only when a single icon needs to break from the surrounding text color.

Can I give one icon a different color from the surrounding text?

Yes. Pass an explicit stroke (or fill) on that single icon, such as stroke='#2563eb', or wrap it in an element that sets its own color. currentColor only applies when you leave the color unset, so an override on one icon does not touch the rest.

Get started

Install the package and let your theme drive the color:

npm i @geoicons/react

import { Japan } from '@geoicons/react/countries';

export default function App() {
  return (
    <span className="text-slate-900 dark:text-slate-100">
      <Japan aria-label="Japan" />
    </span>
  );
}

For every prop each icon accepts, see the GeoIcons API reference. To learn why importing icons this way keeps your bundle small, read why an icon library doesn't have to bloat your bundle. New here? Start with adding your first country icon or browse all 799 icons.

Introducing GeoIcons: 799 tree-shakable geographic icons

Rushan — Wed, 15 Jul 2026 06:27:44 +0000

GeoIcons is a library of geographic map icons for the web: 255 countries, 167 areas, and 377 subdivisions, 799 icons in total at the time of this post, built for React, Vue, Angular, and vanilla JS. More is on the way, including flags. Every icon is a named export, so your bundler keeps only the ones you import. Here are three of them, inheriting the current text color:

What ships in the box

The set covers 255 country icons, named by their ISO 3166 alpha-2 code, and 167 area icons for regions, continents, landforms, and subdivisions. Enough to build a country picker or label a map legend without a second asset library.

Every icon is a single SVG component. No sprite sheet to host and no font to load.

One import ships one icon

GeoIcons has no central registry and no <Icon name="us" /> string API. Each icon is its own named export, which is what lets bundlers drop everything you never reference:

import { UnitedStates, France, Japan } from '@geoicons/react/countries';

export function Legend() {
  return (
    <ul>
      <li><UnitedStates aria-label="United States" /> United States</li>
      <li><France aria-label="France" /> France</li>
      <li><Japan aria-label="Japan" /> Japan</li>
    </ul>
  );
}

Import three icons and your build includes three icons. The other 419 never touch your bundle. For the mechanics behind that, read why an icon library doesn't have to bloat your bundle.

Themeable with currentColor

Icons paint with currentColor, so they follow the text color of whatever wraps them. Change weight with strokeWidth, or fill them solid. No CSS overrides, no per-icon color props to thread through your components:

// Default, colored, heavier stroke, filled
<Nigeria />
<Nigeria stroke="#2563eb" />
<Nigeria strokeWidth={1.5} />
<Nigeria fill="currentColor" />

The same four, live:

Because color is inherited, the same icon works in light mode, dark mode, and on a colored button without any extra styling.

Accessible by default

Icons are decorative unless you say otherwise. Add a label and the icon becomes meaningful to screen readers:

<UnitedStates aria-label="United States" />

Under the hood each icon namespaces its <title> id with React's useId(), so rendering the same icon twice on a page never produces duplicate ids.

Four frameworks, one icon set

The same icons ship for every major framework, imported the same way:

import { UnitedStates } from '@geoicons/react/countries';   // React
import { UnitedStates } from '@geoicons/vue/countries';     // Vue
import { UnitedStates } from '@geoicons/angular/countries'; // Angular
import { UnitedStates } from '@geoicons/vanilla/countries'; // Vanilla JS

@geoicons/core holds the shared pieces the framework packages build on.

Naming you can guess

Countries use their ISO 3166 alpha-2 code in PascalCase: Us, Fr, Jp, De, Br. Areas use a slug in PascalCase, such as EuropeanUnion. If you know the country code, you know the import name, so autocomplete does most of the work.

Licensing

GeoIcons is dual-licensed. It is free under GPLv3 for open-source and GPL-compatible projects, and a commercial license covers everything else. Icons render the same either way. An unlicensed commercial use logs an offline console warning and nothing else, so nothing breaks at runtime.

Get started

Install the package for your framework and import your first icon:

npm i @geoicons/react

import { UnitedStates } from '@geoicons/react/countries';

export default function App() {
  return <UnitedStates aria-label="United States" />;
}

Full API, styling, and accessibility docs live in the docs, or browse all 799 icons to find what you need.

DEV Community: Rushan

How to add country icons to a React app

Step 1: Install the React package

Step 2: Import by ISO code

Step 3: Render and style

Make it accessible

How do I render a country icon at runtime?

Beyond countries: areas

FAQ

How do I add a country icon to a React app?

How do I show an icon for a country chosen at runtime?

Get started

SVG icons in React Server Components: what ships to the client

Step 1: Find out whether your icon library is a Client Component

Step 2: Render icons directly in a Server Component

Step 3: Keep the provider at a client boundary

Step 4: Verify what reached the browser

When you do need "use client"

Do GeoIcons work in React Server Components?

Why can an icon component call useId and still be a Server Component?

How do I check whether my current icon library forces a client boundary?

Does wrapping my app in IconProvider make every page a Client Component?

Can I use the same icon in both a Server Component and a Client Component?

Where this leaves you

Why an icon library doesn't have to bloat your bundle

What tree-shaking does

Why icon libraries are where it breaks

How GeoIcons is built to stay shakable

See it in your own bundle

Ways to accidentally defeat it

Why the bytes matter

FAQ

Does importing one icon include all 799?

Why does an <Icon name=\

How do I confirm tree-shaking works in my app?

Get started

Making SVG icons screen-reader accessible: titles, aria-labels, and unique IDs

Why is my SVG icon invisible to screen readers?

Decorative icons should say nothing

Meaningful icons need an accessible name

Why does the <title> need a unique id?

Icon-only buttons: label the control, hide the icon

The same rules in Vue, Angular, and vanilla JS

How do I verify it works?

FAQ

ISO 3166-1 Alpha-2 Country Codes: A Developer's Guide

What alpha-2 covers

Five kinds of code

The United Kingdom is GB

Kosovo sits outside the standard

Codes get recycled

Names change, codes hold

Subdivisions live in part 2

Regions have no country code at all

Rules for your codebase

How GeoIcons maps to the standard

FAQ

How many ISO 3166-1 alpha-2 codes are there?

Is the country code for the United Kingdom GB or UK?

What is Kosovo's ISO country code?

Should I store alpha-2 or alpha-3 codes?

Do I have to import GeoIcons by ISO code?

Do ISO country codes ever change?

Get started

Visual Alignment for Icons and Labels in Tailwind CSS

Anchor the visual centers

Match icon size to line height

Correct asymmetric visual weight

Put it together: common UI patterns

Buttons

List rows

Inputs

Inline with text

Why Map Shape Icons Beat Flag Emojis for Country Selectors

The Windows rendering gap

Design consistency: Flags versus map shapes

Beyond ISO countries: Mapping markets and regions

Scaling and positioning

Making the transition

FAQ

Why does the `<title>` need a unique id?