TypeScript icon, indicating that this package has built-in type declarations

0.1.4 • Public • Published

Country Flag Emoji Polyfill

screenshot of broken emojis

Recent Windows versions (finally) support emojis natively, but they still do not support pretty country flags. By extension, all Chromium-based browsers can't display country flag emojis natively.

In short, if "🇨🇭" looks like "ᴄʜ" and not like a flag, then this polyfill is for you.

This module is sponsored by TalkJS, a Chat API with pre-built UI for web & mobile apps.

talkjs logo


1. With NPM:

npm install country-flag-emoji-polyfill
import { polyfillCountryFlagEmojis } from "country-flag-emoji-polyfill";

// ...


Or, just with a script tag:

Thanks to the excellent Skypack CDN, you can also use this polyfill without NPM:

<script type="module" defer>
  import { polyfillCountryFlagEmojis } from "";

This code only works on browsers that support ES Modules, but Chromium has done so for quite a while so it should work appropriately.

See here for a full working example (source)

2. Update your CSS

This will load a webfont called "Twemoji Country Flags" on relevant browsers. Next, prefix your font-family CSS with this font everywhere where you want country flags to work. Eg if your CSS currently has this:

body {
  font-family: "Helvetica", "Comic Sans", serif;

then you want to change it to

body {
  font-family: "Twemoji Country Flags", "Helvetica", "Comic Sans", serif;

This is safe because the font is loaded such that the browser will only use it for country flag emojis and not for any other characters. Therefore, the browser will simply use the next font in the list for every character except country flags.

Furthermore, browsers that have native support for country flags will not load font at all, and therefore will simply ignore it in the font-family list. Browsers that do not have native country flags will render country flags using "Twemoji Country Flags" and all other characters as before.


function polyfillCountryFlags(fontName?: string, fontUrl?: string): boolean;

Injects a style element into the HEAD with a web font with country flags, iff the browser does support emojis but not country flags.

  • fontName - Override the default font name ("Twemoji Country Flags")
  • fontUrl - Override the font URL (defaults to a jsdeliver-hosted)

Returns true iff the web font was loaded (ie the browser does not support country flags, but it does support regular emojis).


Firefox on Windows adds country flag emoji support falling back on their Twemoji Mozilla font, which itself is simply all Twemoji emojis concatenated into a single huge color font.

Chromium, however, apparently does not plan to support country flags on Windows, except if Windows itself adds it. This means that Chromium-based browsers such as Chrome, Edge and Brave won't likely support it soon either. That's a huge chunk of browser users, who will complain that other people's nice flag emojis look to them like "ᴄʜ" and not like a picture.

Until either Microsoft or Google recognize how ridiculous this is, you're stick with this polyfill.

How it works

This polyfill merely combines other people's hard work.

The key building block of this polyfill is a font, "Twemoji Country Flags", a subset of "Twemoji Mozilla" made using the excellent pyftsubset tool from fonttools.

This is important, because Twemoji Mozilla is 1.5MB, which is a pretty huge hit on your app perfomance. The subset is only 78kb, which is much better.

It then injects some CSS to load this font as a webfont, but only if the browser supports regular emojis and not country flags. It uses the excellent is-emoji-supported for all the heavy lifting.

As far as I can tell, all browsers that have this problem support WOFF2 fonts, so I made no effort to do the usual multi-font-format @font-face syntax (with eg ttf and woff fonts also).

How to build

This might need updates if Twemoji Mozilla gets new version - especially if new country flags are added.

  • clone the repo
  • make sure you're on a system with bash, fonttools and curl (On my WSL, a single apt install fonttools was enough)
  • run npm run make-font
  • find the new font in dist/TwemojiCountryFlags.woff2




npm i country-flag-emoji-polyfill

DownloadsWeekly Downloads






Unpacked Size

103 kB

Total Files


Last publish


  • eteeselink