circle-flags holds its flags to eleven colours and three exceptions

Every flag is one predictable URL

The entire interface is a filename convention. Flags live under `/flags/` with an ISO 3166-1 alpha-2 code:

https://hatscripts.github.io/circle-flags/flags/xx.svg

So Brazil is `br.svg`, China is `cn.svg`, the United Kingdom is `gb.svg`. A row of them at 48 pixels wide renders as a familiar stack of circular flags:

<img src="https://hatscripts.github.io/circle-flags/flags/br.svg" width="48" />
<img src="https://hatscripts.github.io/circle-flags/flags/cn.svg" width="48" />
<img src="https://hatscripts.github.io/circle-flags/flags/gb.svg" width="48" />

There is no JavaScript, no sprite sheet and no font. That is the design decision, and it is why the set works inside an existing application without any integration work: an `img` tag is the whole dependency.

Because files are named by country code, the set also covers subdivisions and other categories. The repository description says country, state and language flags, and the repository topics list states and languages alongside countries. The palette section confirms this with filenames you would not guess: `es-ib.svg` for the Balearic Islands, `aq-true_south.svg` for True South in Antarctica, and `td.svg` for Chad.

The gallery at https://hatscripts.github.io/circle-flags/gallery is where you browse everything, which matters because the codes are the only way to know whether your target is present.

The colour palette is the specification, and it is enforced

The most substantive thing in this repository is not the artwork, it is the constraint on the artwork. The README states that submitted flags should conform to a specific palette and instructs contributors to try to match the flag's original colours with the nearest colour from that palette.

The palette is eleven colours:

`#eeeeee` white, `#acabb1` gray, `#333333` black, `#a2001d` dark red, `#d80027` red, `#ff9811` orange, `#ffda44` yellow, `#6da544` green, `#496e2d` dark green, `#338af3` light blue, `#0052b4` blue.

Eleven colours across 400-plus flags means every set looks like it came from the same studio, which is the entire point for a picker where users compare options side by side. The usual failure mode with a flag set is visual noise, and the palette is the mechanism that prevents it.

Then come the three exceptions, and they are documented with such precision that they explain the palette's design constraints rather than breaking them:

`#002266` dark blue is used twice only, for Chad and True South in Antarctica. The reason given is to differentiate Chad from Romania. `#4a1f63` purple is used once, for the Balearic Islands. `#751a46` dark pink is used once, for Qatar.

Every other flag uses only the eleven.

The exceptions are individually justified by legibility, which tells you the palette is a considered set rather than an arbitrary sample. Light blue `#338af3` and blue `#0052b4` exist as a pair so that flags needing two blues have them, and dark blue is carved out precisely because the blue pair could not separate those two cases.

Contributing means running svgo, not hand-optimising

The contribution path is short and has one real requirement. You need the latest version of svgo installed, you edit the relevant SVG files in the `flags/` directory, and then you optimise them:

svgo ./flags --recursive --config=svgo.config.js

The `--config=svgo.config.js` is not optional decoration. The repository root contains `svgo.config.js`, so the optimisation settings are part of the project rather than your machine, and every flag in the directory goes through the same pass with `--recursive`. Hand-written SVG that skips svgo will not match the rest of the set, whether in path precision or in what the optimiser strips.

After that you commit and open a pull request. The repository root confirms the shape: a `flags/` directory holding the assets, `gallery.css` and `gallery.md` for the browsable gallery, a `logo.svg`, an `og-image.png` for link previews, a `_config.yml` and `_layouts/` for the GitHub Pages Jekyll site, and `.gitattributes` for line ending handling.

The default branch is `gh-pages`, not `main`, which is worth noting for two reasons. First, clone the repository and you are on the branch being published, so what you edit is what is served. Second, the README's own palette links point at paths like `blob/gh-pages/flags/td.svg`, confirming that the deployed site and the working branch are the same thing.

That single-branch arrangement also means there is no version history to diff a flag against, so a visual regression is something you notice rather than something a pull request surfaces.

Four framework packages exist because plain img tags are not enough everywhere

The README recommends a different package per framework, and the pattern tells you what problem each solves.

For React there is `react-circle-flags`, for React Native and Expo there is `react-native-circle-flags`, and for SolidJS there is `solid-circle-flags`. None of them is this repository; each is a separate npm package that wraps the same SVGs for a framework whose rendering model differs.

That is a sensible division. An `img` tag works in server-rendered HTML and in a browser, but not inside a React Native view tree, and not inside a SolidJS component where you would rather have a component than a URL string. A thin wrapper per framework keeps the SVG set in one place without pretending every renderer behaves the same way.

If you want the assets as a dependency rather than hotlinked, the README gives an install straight from the GitHub repository:

npm install --save https://github.com/HatScripts/circle-flags

Vendoring through git rather than a registry is unusual and has a practical consequence. You get the whole repository including the gallery and config files, and you take updates when you pull, with no published version to pin against. The npm package name here is `circle-flags` at version `1.0.0`, and the tagged releases on the repository are the `v2.x` line, with v2.8.0 on 2025-12-13 and v2.7.0 from 2023-09-25. So the registry version and the tag history are two different numbering systems, which is exactly the kind of detail to check before you pin.

Two userscripts by the same author show the set in use: Google Translate Filter and Flags, and Wiktionary Filter and Flags, both of which filter languages and show country flags.

Where these flags are the wrong asset

The clearest wrong case is anywhere flag accuracy is the point. These are simplified renditions on eleven colours. They are recognisable as icons, and they are not flags. A government site, an election page, an official document or anything with civic meaning needs the real design.

The second wrong case is accessibility by colour alone. Every file is a visual artefact with no text alternative built in, so a country picker built from these needs an adjacent label or an accessible name for each option. There is also a contrast question: eleven fixed colours across 400 files will produce some pairs that fail a contrast check against their neighbours, and the palette does not claim to guarantee that.

The third is a hotlink-dependent deployment. The default URL is GitHub Pages on the `gh-pages` branch with no version in the path, so a flag can change without your deployment changing. For anything long-lived, copy the files into your own repository or package and treat them as an asset you own.

On maintenance, the numbers are mixed and worth stating plainly. The last push was on 2026-07-26, inside a six month window of today's date, and the repository is not archived. But v2.7.0 and v2.6.3 were both tagged on 2023-09-25, minutes apart, and v2.8.0 did not arrive until 2025-12-13. For an asset collection that changes rarely, that is unremarkable, but it does mean you should not expect new countries appearing quickly.

The licence is the simplest thing here: MIT, in `LICENSE.md`, with no restrictions on commercial use.

Editorial conclusion

Use circle-flags when you need a country or language icon that reads at small sizes and must stay visually consistent across a whole set, since the eleven colour palette is enforced and the SVGs are served as individual files you can hotlink or vendor. Do not use it where the flag needs to be legally accurate, where national symbols carry meaning beyond a colour swatch, or where colour alone carries meaning for screen reader users, since each file is purely visual. Before you ship, copy the files rather than hotlinking, because the default branch is `gh-pages` and the served URL has no version pinning, and check the three exceptions named in the README, `#002266`, `#4a1f63` and `#751a46`, since a flag outside the palette will not match a designer's expectation.

Frequently asked questions

Official sources

1. HatScripts/circle-flags on GitHub
2. License: MIT
3. Project website
4. README
5. Releases