country-flag-icons review
country-flag-icons 1.6.20 packages simplified SVG flags behind country-code imports. It publishes 3:2 artwork, square crops, React components, SVG strings, one CSS sheet, and Unicode regional-indicator helpers. Our install had bundled types, and both require() and ESM import worked. The set includes ISO 3166-1 codes plus documented reservations and subdivisions, so it is artwork rather than an authority on countries, names, borders, or political status.
country-flag-icons 1.6.20 installed in 2.3 seconds and used 22 MB in our sandbox, while a full JavaScript import bundled to 0.8 KB gzipped with 0 audit findings. Install it for code-addressed SVG artwork; do not use its icon list as a country database.
We installed it
| Install | ✓ · 2.3s | 3 packages on disk · 22 MB |
| Import | ✓ | ESM import works · require() works · ESM package with exports map |
| Browser | 0.8 KB | gzipped (1.5 KB minified), bundled with esbuild |
| Types | ✓ | TypeScript types bundled |
| Known vulns | 0 | 0 critical · 0 high · 0 moderate · 0 low (npm audit) |
Answers from our run
Does country-flag-icons install cleanly?
Yes. In a fresh container with an empty cache, npm install country-flag-icons finished in 2 seconds, leaving 3 packages and 22 MB on disk. npm audit reported no known vulnerabilities.
How much does country-flag-icons add to a browser bundle?
0.8 KB gzipped (1.5 KB minified) when the whole package is bundled for the browser with esbuild. Importing only part of it is usually smaller.
Does country-flag-icons work with both ESM and CommonJS?
Yes. Both import 'country-flag-icons' and require('country-flag-icons') worked in Node 22 in our run. The package is published as ESM with an exports map.
Does country-flag-icons include TypeScript types?
Yes, type declarations ship inside the package, so no @types install is needed.
country-flag-icons or flag-icons: which should you use?
flag-icons: Use it for a CSS-first collection with familiar fi classes. country-flag-icons 1.6.20 installed in 2.3 seconds and used 22 MB in our sandbox, while a full JavaScript import bundled to 0.8 KB gzipped with 0 audit findings.
When should you not use country-flag-icons?
You require official high-detail flag artwork; the README says these shapes are simplified for small displays
Use it if
- Your records already carry uppercase country codes and the UI needs consistent small SVG flags
- A React screen should import individual 3:2 or square flag components instead of maintaining local SVG files
- Server output needs raw SVG strings or image URLs from the same visual set
- You want hasFlag() and countries to guard a finite icon lookup
- You require official high-detail flag artwork; the README says these shapes are simplified for small displays
- You need individually designed square flags; the 1:1 assets are crops of the 3:2 drawings
- Every accepted code must be an official country; the package also includes exceptional reservations, user-assigned codes, and selected subdivisions
- A page shows only a few flags but would import flags.css; that sheet embeds the entire collection as data URLs
- Emoji must look the same everywhere; the README warns that unsupported systems can show missing glyphs or the two country letters
Setup reality
Our clean Node 22 install of country-flag-icons 1.6.20 completed in 2.3 seconds. It left 3 packages occupying 22 MB, although the package declares 0 direct and 0 peer dependencies; its unpacked archive is 21,776 KB. npm audit found 0 known vulnerabilities. This is an ESM package with an exports map, and require() plus ESM import both succeeded. Types are included. An esbuild import of the package measured 1.5 KB minified and 0.8 KB gzipped.
There are no credentials, native builds, or config files. Pick the published surface before coding: react/3x2 and react/1x1 expose components, string/3x2 exposes markup, and the root exports hasFlag plus countries. React is still needed when importing a component even though 1.6.20 declares no peer. A one-country subpath is easier to audit than trusting every bundler to remove hundreds of unused flag modules.
The CSS route puts every SVG into one data-URL sheet and uses classes such as flag:US with --CountryFlagIcon-height. Raw SVG files live in the npm archive and on the documented mirrors, but application code should not assume an undeclared JavaScript export for an asset path. Normalize incoming codes to uppercase and call hasFlag() before choosing a URL. Supply accessible text because the picture does not tell a screen reader the country name.
Patterns
Check a code before rendering render-react-flag
import { US } from 'country-flag-icons/react/3x2';
export function CountryBadge() {
return <US role="img" aria-label="United States" style={{ width: 30 }} />;
}hasFlag() returns a boolean for the package's own list. It does not certify that the code is an official ISO country.
List every packaged code import-one-react-flag
import US from 'country-flag-icons/react/3x2/US';
const icon = <US title="United States" className="country-icon" />;countries is the package inventory, including documented reservations and subdivisions in addition to ISO 3166-1 entries.
Import one 3:2 React flag render-square-crop
import JP from 'country-flag-icons/react/1x1/JP';
const avatarFlag = <JP role="img" aria-label="Japan" width={32} height={32} />;The country subpath limits the application import to US instead of selecting from a component map at runtime.
Choose a flag dynamically in React validate-country-code
import { hasFlag } from 'country-flag-icons';
const code = String(input).trim().toUpperCase();
const safeCode = hasFlag(code) ? code : null;A namespace lookup can select a component from an uppercase code, but missing input needs a fallback after hasFlag().
Render the square crop list-supported-codes
import { countries } from 'country-flag-icons';
const options = countries
.filter((code) => countryNames[code])
.map((code) => ({ code, label: countryNames[code] }));The 1:1 component is a crop of the 3:2 source artwork, not a separately composed square flag.
Use one raw SVG string render-hosted-svg
const code = 'CA';
const src = `https://purecatamphetamine.github.io/country-flag-icons/3x2/${code}.svg`;
const image = <img src={src} alt="Canada" width="30" height="20" />;The string subpackage returns SVG markup. Treat application-supplied code as a lookup key, not as markup to concatenate.
Load a hosted SVG image use-css-flags
import 'country-flag-icons/3x2/flags.css';
export function Flag() {
return <span className="flag:DE" role="img" aria-label="Germany" />;
}The documented mirror accepts an uppercase filename. Provide an alt value because the URL supplies no accessible country name.
Use the full CSS collection size-css-flag
.country-row .flag\:FR {
--CountryFlagIcon-height: 24px;
}
flags.css embeds the whole set as data URLs. This route favors convenience over importing only the flags a page displays.
Set CSS flag height get-svg-string
import { GB } from 'country-flag-icons/string/3x2';
const html = `<span class="flag-wrap">${GB}</span>`;--CountryFlagIcon-height controls the embedded icon height. The package defaults to 1em when the variable is absent.
Create a Unicode regional flag import-one-svg-string
import US from 'country-flag-icons/string/3x2/US';
console.log(US.startsWith('<svg'));Unicode flags depend on operating-system emoji support, so the same two-letter input may render as letters on older systems.
Copy packaged SVG assets render-unicode-flag
import getUnicodeFlagIcon from 'country-flag-icons/unicode';
import { hasFlag } from 'country-flag-icons';
const code = 'AU';
const flag = hasFlag(code) ? getUnicodeFlagIcon(code) : '🏳';The npm archive contains minified files under 3x2. The README advises against copying unminified repository sources.
Handle an unavailable code map-dynamic-react-flags
import { CA, GB, US } from 'country-flag-icons/react/3x2';
const flagByCode = { CA, GB, US };
export function FlagFor({ code, label }) {
const Component = flagByCode[code];
return Component ? <Component role="img" aria-label={label} /> : null;
}A failed hasFlag() check should choose text or a placeholder before constructing an asset URL.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| flag-icons | npm | Use it for a CSS-first collection with familiar fi classes. |
| react-world-flags | npm | Use it when one React component receiving a code is the preferred API. |
| react-country-flag | npm | Use it for a compact React wrapper around SVG and Unicode output. |
| emoji-flags | npm | Use it when emoji plus country labels are enough and platform rendering can vary. |
More web frontend guides
postcss · react · react-dom · tailwindcss · htmlparser2 · tailwind-merge · the whole shelf →
How this guide is made: grounded in the library's documentation, release notes, changelog, and issue history, on a fixed rubric — not a hands-on install of every release. The 50 most-downloaded entries are additionally install-verified in clean containers. Corrections: contact the desk.