Country Code Flags: ISO Codes, SVG Packs and Emoji Tested

Flag codes are lowercase ISO 3166-1 alpha-2. We tested all 249 across SVG packs and emoji: where UK, EU and XK fail, the heaviest files, and a safe snippet.

Amit Yadav
16 min read
On this page

A country code flag is a flag file or emoji picked by a two-letter ISO 3166-1 alpha-2 code, such as us, de or in. ISO lists 249 of these codes, and they are the file names in almost every flag pack, but the common mistakes (uk for gb, en for a country, an uppercase URL) each fail in a different way.

We tested the 249 codes on 2026-11-05 against four SVG sources and the emoji in Chrome 156 on Linux, and measured every file. Windows was not tested, and the limits are listed.

Quick answer

  • Use lowercase alpha-2 for SVG files. Every URL host we tried returned 404 for uppercase US. Use GB for the United Kingdom, because UK is not an official code.
  • flag and circle-flags cover all 249 codes on our URLs. flagpack covers 248 and draws England's cross for gb, so its UK flag is gb-ukm.
  • A language code is not a flag code. Of 183 two-letter language codes, 76 point to a different country: ar is Argentina, sv is El Salvador.
  • Emoji flags depend on the font. Chrome on Linux with Noto drew all 249. Microsoft says Windows shows two letters instead. We did not test Windows.
  • Watch the heaviest files. Serbia is 181,634 bytes in flag-icons, against a median of 761. A picker built with its CSS classes downloads all 249 files.

What the codes are

ISO 3166-1 defines three codes for each place: alpha-2 (gb), alpha-3 (gbr) and numeric (826). Flag packs use alpha-2 because it is short and matches the emoji system.

We counted the official list through a public copy of the data, and it matched Fedora's iso-codes package and Wikipedia: 249 codes, no differences. Four groups outside that list cause most of the trouble:

GroupCodesStatus
Exceptionally reserveduk, eu, un, ac, cp, dg, ea, ic, taNot official countries
User-assignedxk (Kosovo)Common, not assigned by ISO
Retiredsu, yu, an, csOld data still contains them
Subdivisionsgb-eng, us-tx, es-ctISO 3166-2, not alpha-2

gb is the official code for the United Kingdom. uk is only reserved, which is why most packs have no such file.

Which packs cover which codes

Every count below is a live request for each code, except the npm rows, which count files in the package.

SourceISO codesBeyond ISOTrap
flag (flag-icons)249 of 24922, such as eu, un, xk, gb-eng, es-ctOur URL needs -4x3 or -1x1
circle-flags249 of 249181 in npm, plus a language setSimplified emblems
flagpack248 of 249gb-eng, gb-sct, gb-wls, gb-ukmbq is 404; gb is England
flagcdn249 of 24950 us-*, eu, un, xk, gb-*No uk
country-flag-icons (npm)249 of 24916Files only, 3:2

Other versions: flag-icons 7.6.0, circle-flags 2.8.3, flagpack-core 2.1.0, country-flag-icons 1.6.20, all MIT. All SVG Icons serves the first three, so this is not an independent review. In circle-flags, bq, bv, hm, sh, sj and um work as URLs but do not show in our pack grid.

Some sets name files after the country, not the code: tabler-flags uses united-states, and the twemoji, openmoji and emojione packs use a flag- style prefix. A slug built from the English country name matched only 219 to 234 of the 249, so those packs need a hand-checked lookup table. Browse them all in the flags collection.

The codes that break

The same input gives different results per source. Here is what each one returned, including the emoji row.

A table of 12 tricky flag codes across circle-flags, flag, flagpack, flagcdn and emoji. uk works only in circle-flags, flagpack shows England for gb, and invalid emoji show a grey question mark flag

Three results to fix in your code, not your data:

  • gb on flagpack is England's cross, not the Union Jack, and gb-nir draws the Union Jack. The file exists and returns 200, so nothing warns you. Use gb-ukm there, which the package README confirms.
  • xx is a useful placeholder on only two sources. circle-flags draws a grey question mark disc and flag-icons draws an empty box. flagpack and flagcdn return 404.
  • su still draws the Soviet flag on circle-flags, while the other three return 404. Do not treat a 200 as proof that a code is valid.

Also, on a pinned jsDelivr copy, flag-icons has no ac, ea, ta or cq, although our flag URLs do serve ac, ea and ta.

A language code is not a flag code

A locale says which language someone reads, and a flag says which country a thing belongs to. Using one for the other picks the wrong flag more often than you would expect, because the two lists share letters.

We checked all 183 two-letter language codes that Node's Intl names, with Node 24 and CLDR 48:

Result as a flag codeCountExamples
Different country76ar Argentina, sv El Salvador, ca Canada
No such country74en, hi, ja, ko, zh, uk, ta
Same place33de, fr, es

Parse the locale, and take the region only if the user's locale actually names one. Guessing with maximize() picks a default, which is a claim about the reader:

new Intl.Locale('en-GB').region;            // 'GB'
new Intl.Locale('en').region;               // undefined
new Intl.Locale('en').maximize().region;    // 'US'
new Intl.Locale('ar').maximize().region;    // 'EG'
new Intl.Locale('es-419').region;           // '419', a world region, no flag file

For a language switcher, the honest default is text: each language in its own name, such as Deutsch or العربية. Arabic is spoken in over 20 countries, and no single flag says which. The W3C guide to language tags explains the tag format, and the rules are in BCP 47.

If you do want language icons, circle-flags has a separate set: our lang-en and lang-ar URLs, or flags/language/ in the npm package. There, lang-ar is Arabic while ar stays Argentina.

Flag URLs and CSS classes

All of these use the lowercase code. Uppercase US returned 404 on our three URLs, flagcdn's SVG path and the flag-icons and circle-flags copies on jsDelivr.

SourceFormat
Our circle-flagshttps://i.allsvgicons.com/circle-flags/us.svg
Our flaghttps://i.allsvgicons.com/flag/us-4x3.svg
Our flagpackhttps://i.allsvgicons.com/flagpack/us.svg
flagcdn SVGhttps://flagcdn.com/us.svg
flagcdn PNGhttps://flagcdn.com/w40/us.png
jsDelivrhttps://cdn.jsdelivr.net/npm/[email protected]/flags/4x3/us.svg

Caching differs: our API sent a 7-day max-age, flagcdn about 31 days, and pinned jsDelivr files a year with immutable. flagcdn's other sizes are on the Flagpedia API page.

flag-icons also ships as CSS. After loading its stylesheet, <span class="fi fi-us"></span> draws a 4:3 flag, and adding fis makes it square. The next two sections explain when to avoid that.

Which flag files are heaviest

Most flags are tiny. A few detailed coats of arms are not, so the total is dominated by a short list. Sizes are raw bytes for the 249 ISO codes:

SourceMedianTotalHeaviest
flag-icons 4:37611,637,404rs 181,634, bo 102,880, mx 84,753
circle-flags559163,395io 3,522, ki 2,827, sa 2,684
country-flag-icons 3:2479164,500io 5,321
flagpack (our URLs, 248)940859,760sa 93,827, bt 59,692, ar 56,957
flagcdn SVG5833,783,351sv 248,937, bo 240,385, af 222,005

In flag-icons, the 10 heaviest files are 45.1% of the total. Serbia is still 49,805 bytes with gzip, while the heaviest circle-flags file is 839. circle-flags stays small because it simplifies emblems. At 20 pixels nobody can read the Serbian arms anyway, but at hero size you will see the difference.

Small files win for a list, and the detailed set is better for one large flag.

What a country picker downloads

We built a 249-row list in a 320-pixel scroller, served it locally, and counted the SVG requests in Chrome 156 before any scrolling:

MarkupSVG requestsSVG bytes
flag-icons CSS, fi fi-xx2491,637,404
<img> flag-icons, no lazy2491,637,404
<img loading="lazy"> flag-icons49338,232
<img loading="lazy"> circle-flags4927,958

The CSS classes do not defer anything, because every row sets a background image and Chrome fetched all of them on load, even for rows far below the scroller. The stylesheet adds 28,018 bytes (2,357 with gzip) on top. For one flag that is fine: a page with a single fi-us fetched only that one 648-byte file.

Switching to lazy <img> with circle-flags cut the download from 1.6 MB to 28 KB in this test. Give each image width and height so the list does not jump. Leave alt empty when the country name sits beside it, as our guide to accessible SVG icons explains.

A plain <select> cannot hold images, unless you use the new customizable select. Chrome 156 accepted appearance: base-select with an <img> inside an <option>. MDN marks customizable select as limited availability, and browsers without support keep the text. We only checked that Chrome parses it and keeps the image, not how a full picker behaves.

How emoji flags work

There is no flag character for each country. A flag emoji is two regional indicator symbols, one per letter of the code, and the font decides whether the pair becomes a flag. US is U+1F1FA U+1F1F8, and that string has a JavaScript length of 4.

Unicode's emoji-test 18.0 list has 259 of these pairs: all 249 ISO codes plus ac, cp, cq, dg, ea, eu, ic, ta, un and xk. England, Scotland and Wales are a different kind of sequence, a black flag plus tag letters, and they are the only subdivisions on the list:

const tagFlag = (code) => '\u{1F3F4}' +
  [...code.replace('-', '')].map((c) =>
    String.fromCodePoint(0xE0000 + c.charCodeAt(0))).join('') + '\u{E007F}';

tagFlag('gb-eng'); // England. 'gb-nir' and 'us-tx' showed the question mark flag.

We drew each pair on a canvas and compared the pixels in Chrome 156 on Fedora with Noto Color Emoji:

  • ISO codes: all 249 differed from the placeholder.
  • Extras: all 10 differed too.
  • Invalid pairs: uk, su, an, yu, aa, qx, xx, en and ja were pixel-identical to zz, a white flag with a question mark.
  • Shared art: au and hm, fr and mf, bv, no and sj, and um and us use the same image, so 244 pictures cover the 249 codes.
Windows: not tested by us

We had no Windows machine in this test. A Microsoft Q&A reply from September 2025 says Segoe UI Emoji has no national flags, so Windows shows the two-letter code. A Mozilla bug describes the same font behaviour, and adds that Firefox on Windows prefers its bundled font instead. Assume Chrome on Windows shows letters until you check it on your own machine.

We could imitate only part of that on Linux. We removed the flag glyphs by giving Chrome a colour emoji font without them, and the result is empty boxes instead of letters, because our font also has no regional indicator shapes. With no emoji font at all, the result was boxes as well.

Three rows of the same eight emoji flags. Noto draws real flags with question mark flags for UK and ZZ, a font without flag glyphs shows empty boxes, and the polyfill font draws flags with letter tiles for UK and ZZ

country-flag-emoji-polyfill 0.1.10 fixes this case. It installs a 78,292-byte web font only when colour emoji work and flags do not. In our three states, it skipped Noto, skipped the machine with no emoji font, and installed on the stripped font. You must also put "Twemoji Country Flags" first in your font-family, or nothing changes.

Our recommendation: use emoji where a missing flag costs nothing, such as a chat message, and use SVG where the flag has to appear, such as a checkout field. To turn an emoji back into SVG, use the emoji to SVG tool.

A tested code to flag function

This turns user input into a code, an emoji and a URL. It uses an allowlist, because the shorter approach is wrong.

const ISO = new Set('ad ae af ag ai al am ao aq ar as at au aw ax az ba bb bd be bf bg bh bi bj bl bm bn bo bq br bs bt bv bw by bz ca cc cd cf cg ch ci ck cl cm cn co cr cu cv cw cx cy cz de dj dk dm do dz ec ee eg eh er es et fi fj fk fm fo fr ga gb gd ge gf gg gh gi gl gm gn gp gq gr gs gt gu gw gy hk hm hn hr ht hu id ie il im in io iq ir is it je jm jo jp ke kg kh ki km kn kp kr kw ky kz la lb lc li lk lr ls lt lu lv ly ma mc md me mf mg mh mk ml mm mn mo mp mq mr ms mt mu mv mw mx my mz na nc ne nf ng ni nl no np nr nu nz om pa pe pf pg ph pk pl pm pn pr ps pt pw py qa re ro rs ru rw sa sb sc sd se sg sh si sj sk sl sm sn so sr ss st sv sx sy sz tc td tf tg th tj tk tl tm tn to tr tt tv tw tz ua ug um us uy uz va vc ve vg vi vn vu wf ws ye yt za zm zw'.split(' '));
const EXTRA = new Set(['xk', 'eu', 'un']);

function toCountryCode(input) {
  const code = String(input ?? '').trim().toLowerCase();
  if (code === 'uk') return 'gb';
  return ISO.has(code) || EXTRA.has(code) ? code : null;
}

const toEmoji = (code) =>
  code.toUpperCase().replace(/[A-Z]/g, (c) =>
    String.fromCodePoint(c.charCodeAt(0) + 127397));

const toFlagUrl = (code) => `https://i.allsvgicons.com/circle-flags/${code}.svg`;

const flag = (input) => {
  const code = toCountryCode(input);
  return code
    ? { code, emoji: toEmoji(code), url: toFlagUrl(code) }
    : { code: null, emoji: '', url: toFlagUrl('xx') };
};

What we ran it against:

  • All 676 letter pairs: it accepts exactly 253, the 249 plus xk, eu, un and uk.
  • Accepted input: US, us, uk (returned as gb), XK, EU, UN.
  • Rejected input: en-US, en_GB, en, USA, gb-eng, 419, su, yu, an, zz, an emoji, an empty string, null, undefined, 0.
  • Output: all 252 emoji match the Unicode list, and all 253 URLs, including xx, returned a real SVG.

sv still returns El Salvador, because it is a valid country. No validator can tell that you meant Swedish, so parse locales first with Intl.Locale.

Do not swap the set for Intl.DisplayNames. We tried it first, and it accepted 279 pairs, 30 of them not ISO: zz is "Unknown Region", su is "Russia", dd is "Germany". Use Intl to label a country, not to validate one.

An older version of this page fell back to un for unknown codes. That is wrong: it shows the United Nations flag to anyone with a bad code. Use xx on circle-flags, or a neutral icon.

What we did not test

  • Windows, macOS, iOS and Android: the emoji results are one Chrome on Fedora (Chrome 156.0.8078.47, Noto COLRv1).
  • Art accuracy: we checked that files exist and looked at the 12 tricky codes. We did not compare all 249 drawings with official flags.
  • Sizes: raw bytes on 2026-11-05, and only Serbia, Mexico and the circle-flags top file were also measured with gzip.
  • Picker: one desktop viewport on a local server, so counts will shift with row height and the browser's lazy-load distance.
  • Politics: we report which codes exist, not who should use them. xk, tw, ps and eh may need a product decision in your market.
What is a country code flag?
A flag image or emoji chosen by a two-letter ISO 3166-1 alpha-2 code. **us** gives the United States and **de** gives Germany. SVG flag packs use the code as the file name, and emoji build the flag from two regional indicator symbols.
Is the UK flag code UK or GB?
GB is the official ISO code, and UK is only reserved. In our test, flag-icons, flagcdn and flagpack returned 404 for uk, and only circle-flags served it. Map uk to gb, except on flagpack, where the UK flag is gb-ukm.
Why does my flag emoji show two letters?
The font has no flag for that pair. Microsoft says this is how Segoe UI Emoji behaves on Windows, which we did not test ourselves. On Linux with Noto, invalid pairs show a question mark flag instead. Use SVG flags, or the polyfill, where the flag must appear.
Can I use a language code as a flag code?
No. Of 183 two-letter language codes we checked, 76 are a different country as a flag code and 74 are no country at all. **ar** is Arabic as a language and Argentina as a flag.
Do flag packs include Kosovo and the EU?
flag-icons, circle-flags and flagcdn serve xk, eu and un. flagpack returned 404 for all three. None of them are official ISO country codes, but all three have emoji flags.
Which flag files are the smallest?
circle-flags had the lowest total of the code-keyed sets we measured, at 163,395 bytes for 249 flags, and its heaviest file is 3,522 bytes. It simplifies emblems to get there, so use a detailed set for large flags.
How do I show England, Scotland or Wales?
As SVG, use gb-eng, gb-sct and gb-wls, which all four sources serve. As emoji, these three use a tag sequence, not two regional indicators. Northern Ireland has an SVG code but no emoji.

Related posts

Share this post