DEV Community: Rushan

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.

Key takeaways

An icon is either decorative (aria-hidden="true", skipped by screen readers) or meaningful (role="img" plus an accessible name). Every icon should land in one of those two states.

Every GeoIcon is decorative by default. Pass aria-label and it switches to meaningful, adding role="img", a <title>, and aria-labelledby.

Each icon generates a unique id for its <title>, through React's useId() and the equivalent in the Vue, Angular, and vanilla packages, so rendering the same icon twice never produces duplicate ids.

Inside an icon-only button, label the button and leave the icon decorative. Two names on one control is worse than one.

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 { Fr } from '@geoicons/react/countries';

<span>
  <Fr /> 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:

<Fr 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 { Fr, Jp } from '@geoicons/react/countries';

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

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

See it live on geoicons.io →

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:

<Fr aria-label="France" />
<Fr 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">
  <Fr />
</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">
  <De /> Germany
</a>

// Standalone status indicator: nothing else names it, so the icon does.
<Jp 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 { Fr } from '@geoicons/vue/countries';
</script>

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

  <!-- Meaningful -->
  <Fr 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 { Fr } from '@geoicons/angular/countries';
// @Component({ standalone: true, imports: [Fr], 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 { Fr } 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.

See it live on geoicons.io →

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 { Fr, Jp } 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><Fr /> France</li> {/ Meaningful: the icon is on its own. */} <li><Jp 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 422 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.

Key takeaways

ISO 3166-1 defines 249 officially assigned alpha-2 codes. UK is not one of them. The United Kingdom is GB.

Four other status categories exist: user-assigned, exceptionally reserved, transitionally reserved, and indeterminately reserved. They follow different rules.

Kosovo uses XK, a code from the user-assigned range that ISO has never officially assigned.

Codes get recycled. CS meant Czechoslovakia, then Serbia and Montenegro.

Country names change far more often than their codes. Store the code, resolve the name at render time.

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" />

See it live on geoicons.io →

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, EuropeanUnionEu } from '@geoicons/react/areas';

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

See it live on geoicons.io →

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.

Every shape is a separate named export, so importing Us and Jp pulls two icons into your bundle and leaves the other 253 behind. 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 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.

Key takeaways

Flexbox alignment anchors the visual centers of icons and text.

Sizing utilities map the SVG bounds to the text line-height.

Translation utilities correct visual offset in asymmetric country shapes.

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 { Jp } from '@geoicons/react/countries';

export default function CountryBadge() {
  return (
    <div className="flex items-center gap-2">
      <Jp 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">
  <Us 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">
  <Us 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 { It } from '@geoicons/react/countries';

export default function ItalyListRow() {
  return (
    <div className="flex items-center gap-2">
      <It 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 { Jp } 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"
    >
      <Jp 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 { It } from '@geoicons/react/countries';
import { Us } from '@geoicons/react/countries';
import { Jp } from '@geoicons/react/countries';

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

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 { Us } from '@geoicons/react/countries';

export default function CountryInput() {
  return (
    <div className="relative">
      <Us
        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 { It } 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">
        <It 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.

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 { Jp, Fr, De } from '@geoicons/react/countries';
import { EuropeanUnionEu } 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">
  <Jp size={40} /> 
  <Fr size={40} /> 
  <De size={40} /> 
  <EuropeanUnionEu size={40} />
</div>

Key takeaways

Every GeoIcon draws with stroke="currentColor", so it inherits the CSS color of its parent.

To support dark mode, set color for each theme in CSS. You never touch the icon.

A Tailwind class like dark:text-slate-100 works directly on the icon or on any ancestor.

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' }}>
  <Fr aria-hidden="true" /> France
</p>

The <Fr /> 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:

<De
  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">
  <Fr 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:

<Fr 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 { Jp } from '@geoicons/react/countries';

export default function App() {
  return (
    <span className="text-slate-900 dark:text-slate-100">
      <Jp 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 422 icons.

Introducing GeoIcons: 422 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 and 167 areas, 422 icons in total at the time of this post, built for React, Vue, Angular, and vanilla JS. More is on the way, including subdivisions and 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:

Key takeaways

422 icons: 255 countries (ISO 3166) + 167 areas (regions, continents, landforms, subdivisions).

Tree-shakable by design. One import ships one icon, not the catalog.

Themed with currentColor and an adjustable strokeWidth. Accessible out of the box.

React, Vue, Angular, and vanilla JS. Free under GPLv3, commercial license available.

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 { Us, Fr, Jp } from '@geoicons/react/countries';

export function Legend() {
  return (
    <ul>
      <li><Us aria-label="United States" /> United States</li>
      <li><Fr aria-label="France" /> France</li>
      <li><Jp 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
<Ng />
<Ng stroke="#2563eb" />
<Ng strokeWidth={1.5} />
<Ng fill="currentColor" />

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:

<Us 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 { Us } from '@geoicons/react/countries';   // React
import { Us } from '@geoicons/vue/countries';     // Vue
import { Us } from '@geoicons/angular/countries'; // Angular
import { Us } 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 EuropeanUnionEu. 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 { Us } from '@geoicons/react/countries';

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

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

DEV Community: Rushan

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 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

Make your icons follow dark mode automatically with currentColor

What does currentColor do?

Why do hardcoded icon colors break in dark mode?

How do I switch icons for a dark theme?

How do I follow the system setting instead?

Can I recolor an icon on hover?

Outline or solid: stroke versus fill

FAQ

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

Do I need a color prop on every GeoIcon?

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

Get started

Introducing GeoIcons: 422 tree-shakable geographic icons

What ships in the box

One import ships one icon

Themeable with currentColor

Accessible by default

Four frameworks, one icon set

Naming you can guess

Licensing

Get started

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