svg-country-flags: Accurate SVG and PNG Renders of World Flags by ISO Code

What the Repository Contains and the Accuracy Commitment

The hampusborgos/country-flags repository provides SVG source files for every country flag in the world, along with pre-rendered PNG exports at 100px, 250px, and 1000px widths. The goal stated in the README is accuracy: each flag is maintained to match the legal or regulatory description the country itself specifies, not a stylized approximation.

The source SVG files originated from Wikimedia Commons. Where a country's legislation describes the flag more precisely than the Wikimedia version, the repository's maintainers have updated the file and in some cases contributed the correction back to Wikimedia.

Flags are organized in an svg/ directory and named by their ISO 3166-1 alpha-2 two-letter code. For the constituent countries of Great Britain, six-letter codes are used: GB-ENG, GB-SCT, GB-WLS, and GB-NIR. Kosovo uses the user-assigned code XK, which is not part of the formal ISO standard but is in use by several multinational organizations.

A countries.json file at the repository root maps each ISO country code to the corresponding country name in English. This file is the reference for converting a code to a display name in an application.

Installing as an npm Package

The repository is published to npm under the package name `svg-country-flags`. Install it with:

npm install --save svg-country-flags

Version 1.2.10 is the current release as listed in package.json. After installation, the SVG files are available under `node_modules/svg-country-flags/svg/` named by their ISO 3166-1 alpha-2 code. A United Kingdom flag would be at `gb.svg`, a United States flag at `us.svg`. The repository can also be cloned directly or downloaded as a ZIP archive from GitHub. For projects that do not use npm, cloning and referencing the svg/ directory is an alternative path. All flags can be browsed at the online viewer at hampusborgos.github.io/country-flags.

Exporting PNG Files at Custom Widths

The pre-rendered PNG exports at 100px, 250px, and 1000px cover most common use cases. For a different width, the repository provides a Node.js build script.

First install the required global tools:

npm install -g svgexport imagemin-cli
npm run build-pngs -- 1000:

Replace `1000:` with the desired width. The colon after the number is required by the svgexport syntax. To export by height instead, use `:200` for a 200px height. The imagemin-cli step is described as important because svgexport produces uncompressed PNGs that are several megabytes each; imagemin reduces them to practical sizes.

For environments where the Node.js build script is not available, the README provides a manual shell equivalent to run from the svg/ directory:

for file in *.svg; do svgexport $file "`basename $file svg`png" pad 1000: ; done
imagemin *.png --out-dir=../compressed-pngs/
rm *.png

The compressed output ends up in the compressed-pngs/ folder relative to the svg/ directory.

Using Flags in HTML and Front-End Applications

Because each flag is a standard SVG file, it can be embedded in a web page as an `<img>` tag, an inline SVG, or a CSS background image. SVGs scale without quality loss, which makes them preferable to PNG for responsive layouts where the flag display size varies.

The ISO code system makes flag selection straightforward in code: given a country code from a form, an API response, or a locale string, the corresponding SVG file path is predictable without a lookup table beyond the countries.json file for display names.

For applications that need only a small subset of flags, SVGs can be copied individually into a project's asset directory without installing the full npm package. The public domain status documented in package.json (`PD`) means attribution is not required by the license.

Front-end frameworks that bundle assets typically handle the SVG files through their standard import or copy mechanisms. The files are plain SVGs with no proprietary attributes or external dependencies.

Limitations and Maintenance Status

The last push to the repository was on 2026-03-10, which is more than six months before the current date. The project has no GitHub releases and no versioned changelog.

The repository does not include all flags that exist in the world. It follows ISO 3166-1 plus a small number of user-assigned codes like XK for Kosovo. Flags for territories, autonomous regions, or breakaway states that do not have recognized ISO codes are not included.

Flag designs change when countries update their symbols. The accuracy commitment means the repository should reflect current official designs, but without a release cadence or change log, it is not straightforward to determine when a specific flag was last reviewed against the current legal description.

An alternative source for flag assets is the FlagKit project, which also provides SVG and PNG flags. The main difference is that FlagKit packages flags in a format optimized for iOS and Android use alongside web, while this repository focuses on web-friendly npm delivery and has a broader stated accuracy goal tied to legal descriptions. Teams that need verified accuracy for specific flags should compare both sources against official government references.

Editorial conclusion

This repository is the right tool for front-end projects that need all world flags in SVG format, accurately rendered and named by ISO code, without building or sourcing the assets yourself. The npm package `svg-country-flags` version 1.2.10 is the install target. The last push was on 2026-03-10, which is more than six months before the current date, and the repository carries no specified license in its metadata beyond the package.json declaration of `PD` (public domain). Verify that public domain status covers your specific jurisdiction and use case before relying on it for commercial distribution.

Frequently asked questions

Official sources

1. hampusborgos/country-flags on GitHub
2. Issues
3. README