flag-icons: Country Flag Icons in SVG with a CSS Class per ISO Code

The problem flag-icons solves: a country code is not a flag

Most applications store a country as an ISO 3166-1-alpha-2 code such as gr, de or gb. Rendering that as a flag usually means one of three things: bundling a folder of images and writing a lookup table, pulling an icon font that ships hundreds of glyphs you will never draw, or calling a flag API on every render. flag-icons takes the first option and removes the lookup table. The class name is the code. A span with fi and fi-gr draws the Greek flag; there is no mapping layer and no JavaScript in the render path.

The audience is narrow and identifiable. It fits server-rendered pages, static sites, documentation, email-adjacent HTML and admin tables where a country column needs a visual marker next to the code. It also fits projects that already load a stylesheet and would rather add one more file than add a runtime dependency. The README states the collection covers all country flags in SVG, and the repository ships the SVG files themselves under flags/, so the assets are local rather than fetched from a third party at page load.

How the CSS class mechanism actually works

The package is a stylesheet plus an asset directory. Each flag class sets a background image pointing at one SVG file, and the base class supplies the properties that position it. The README gives the three properties the base class applies: background-size: contain, background-position: 50% and background-repeat: no-repeat. That is the whole rendering model. There is no sprite sheet and no icon font, so a browser fetches one small SVG per distinct flag on the page and caches it normally.

The class prefix encodes the element type. Apply fi to an empty span for inline use. Add fis for the squared variant, which uses a different aspect ratio. Use fib instead of fi when the flag goes on an arbitrary element rather than a bare span. The README is explicit that in the fib case the flag is centred inside the element and you must set the size yourself, at a 4 by 3 ratio, or add the squared class. That is a real constraint: the class does not size the element for you in that mode.

The README says that editing the `$flag-icons-included-countries` list in sass/_variables.scss and building again is how you produce a CSS file containing only the countries you need, and the SASS `@use` configuration accepts the same variable. Either way, the build step is part of the workflow rather than something you can skip once and forget.

Installing flag-icons and rendering a first flag

The README offers two install paths. You can download the project archive, or install it from npm or Yarn. The npm route is the one most projects will take.

npm install flag-icons
# or
yarn add flag-icons

After that, import the minified stylesheet. The README shows a path that includes node_modules, which is the literal string it gives rather than a bundler alias, so check how your build tool resolves it.

import "/node_modules/flag-icons/css/flag-icons.min.css";

If you would rather not bundle the CSS, the README also documents a CDN link. Note that the URL pins a specific version in the path, so you should decide deliberately whether to track a version or float it.

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/gh/lipis/[email protected]/css/flag-icons.min.css"
/>

With the stylesheet loaded, a flag is two classes on an empty span. The README gives this exact example, showing the normal and squared variants side by side.

<span class="fi fi-gr"></span> <span class="fi fi-gr fis"></span>

What you should see is the Greek flag inline with the surrounding text, then the same flag in a square. If nothing appears, the usual cause is the stylesheet not loading, since the span has no intrinsic content and no dimensions without it.

Building from source and trimming the country list

The repository is a build project, not only a published package. The README says to run yarn after cloning, then yarn build to compile the SCSS files and yarn start to serve the result on localhost:8000. The package.json confirms the port and the server: the start script runs http-server with -a localhost -p 8000.

yarn
yarn build
yarn start

The SASS entry point accepts configuration. The README shows a use rule with two overrides: a path variable pointing at the flags directory, and an included-countries variable taking a list of codes.

@use "node_modules/flag-icons/sass/flag-icons" with (
  $flag-icons-path: "node_modules/flag-icons/flags",
  $flag-icons-included-countries: ("gr", "de", "gb")
);

That second variable is the piece most worth knowing about if bundle size matters to you; the README also says you can edit the same list in sass/_variables.scss and rebuild. The README points at sass/_variables.scss for the full set of available variables, which is where to look before assuming a given knob does not exist. The build scripts in package.json also reveal that the SVGs are optimised with svgo, and that a Python script regenerates flag identifiers, so the asset pipeline is reproducible from the repository rather than assembled by hand.

Where flag-icons is the wrong choice

The collection is country flags. That boundary is the project's main limitation and it is easy to hit. If your interface needs regional flags, historical flags, organisational flags or language markers, this package does not cover them. A request for an English language flag icon is precisely the kind this project cannot answer: a language is not a country, and there is no language class in the documented API.

The format is another boundary. The repository ships SVG under flags/, and the README describes SVG throughout. There is no documented PNG output, so a pipeline that needs raster images at fixed pixel sizes, such as a slide deck or a print asset, will have to rasterise the SVGs itself. That is a conversion step you own.

The rendering model also imposes a constraint that is easy to miss. Because the flag is a CSS background, it is not an img element. It carries no alt text of its own, and the empty span contributes nothing to assistive technology. If the flag is the only indication of a country, that information is invisible to a screen reader unless you add a text label or an aria attribute yourself. The README does not discuss accessibility at all, which is a genuine gap rather than an oversight you can infer around.

Finally, if your build cannot add a stylesheet, or if you need flags inside a canvas or a PDF generator, a background-image class is the wrong primitive.

Alternatives and how they differ in approach

The most direct alternative is an icon font or a general icon set that happens to include flags. Those approaches deliver glyphs through a font file or a sprite, so a page requests one asset instead of one SVG per flag. The trade-off runs the other way: you load glyph definitions for every icon in the set, and you address a flag by a glyph name rather than by an ISO code. flag-icons keeps the code as the class name, which means a value straight from your database can be interpolated into the class without a translation table.

A second alternative is fetching flags from a remote image service. That keeps the assets out of your bundle entirely and lets you request a specific width. It also adds a network dependency and a third party in the critical path of every flag render. flag-icons serves local files from your own origin, which is a different failure profile: nothing breaks when someone else's service is slow, but the assets are yours to ship and cache.

A third option, and the one worth weighing seriously, is copying the handful of SVG files you actually need straight out of the flags/ directory. The licence permits it. If a project renders five countries, the npm package and its stylesheet are more machinery than the job requires, and the class abstraction buys you nothing over five inline images with proper alt text.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-11-02. The most recent release listed is v7.6.0 from 2026-10-15, after v7.5.0 and v7.4.0 on the same day, 2025-05-29. That pattern suggests releases cluster rather than arrive continuously, so pinning a version and upgrading deliberately is more realistic than tracking the default branch.

The upgrade cost is low but not zero, and it depends on which install path you chose. If you consume the published CSS over a CDN with a pinned version in the URL, upgrading is an edit to that URL. If you use the SASS path with the included-countries variable, upgrading may require re-checking that your variable names still exist in sass/_variables.scss, because those are internal to the project and not covered by any stability promise in the README. If you vendored individual SVGs, upgrades are manual by definition.

The licence is MIT, declared in package.json and shipped as a LICENSE file at the repository root. That permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. This is a description of the licence text, not legal advice; if you redistribute the assets inside a product, have your own counsel confirm the notice requirements are met. One attribution detail is worth knowing because it affects provenance: the README credits the original SVG collection to koppi and notes that it is now deleted, so the flags/ directory is effectively the surviving copy of that work under this project's licence.

Editorial conclusion

Adopt flag-icons if you need static, dependency-free country flags in a page that already loads a stylesheet, and if the ISO 3166-1-alpha-2 code is what your data carries. Do not adopt it if you need PNG output at arbitrary sizes, if you need sub-national or historical flags, or if you cannot add a CSS file to the page. Before committing, check three things in the repository: that every code you use exists under flags/, that the country.json file covers the names you render, and whether the SASS variables in sass/_variables.scss let you trim the included country list, since that is the only supported way to cut the CSS payload.

Frequently asked questions

Official sources

1. License: MIT
2. lipis/flag-icons on GitHub
3. Project website
4. README
5. Releases