flag-icons: Country Flag SVGs with CSS Classes for Web Integration

What flag-icons Provides and Who Uses It

Displaying country flags on a web page requires either storing image files locally or using a service that hosts them. flag-icons solves this by providing every country's flag as a well-maintained SVG, combined with a CSS class system that maps ISO 3166-1-alpha-2 two-letter country codes to the correct flag.

The project is maintained by Panayiotis Lipiridis and published to npm as `flag-icons` at version 7.5.0. The repository is MIT-licensed. The last push was on 10 July 2026. The SVG files are credited in the README to an earlier collection by a contributor named koppi.

Developers who use this package include anyone building country selectors, language switchers, e-commerce storefronts that display shipping destinations, and sports or statistics pages that show national teams. The CSS approach makes the integration as lightweight as adding a stylesheet and a class name.

Installing via npm, Yarn, or CDN

Install the package from npm:

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

Once installed, import the minified CSS in your JavaScript entry point:

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

For projects without a bundler, include the CSS via the jsDelivr CDN:

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

The CDN URL pins to a specific version tag. Pinning prevents unexpected flag changes if the project releases updates. The package.json lists `css/flag-icons.css` as the package main entry point, with `css/`, `flags/`, `sass/`, and `country.json` as the published files.

Inline Usage: CSS Classes and ISO Country Codes

Once the CSS is loaded, add a flag to any HTML element using two classes: `.fi` (the base class) and `.fi-xx` where `xx` is the ISO 3166-1-alpha-2 code for the country. To show a flag inline with text, add the classes to an empty `<span>`. The README shows the basic syntax:

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

The first span displays Greece's flag at the standard 4:3 ratio. Adding the `fis` class produces the squared version of the same flag. Country codes follow the ISO 3166-1-alpha-2 standard, which assigns each country a two-letter code: `gr` for Greece, `de` for Germany, `gb` for the United Kingdom, and so on.

The full list of ISO 3166-1-alpha-2 codes is maintained by the ISO and is available at iso.org/obp/ui/#search/code/. The `country.json` file in the published package provides the code-to-country-name mapping.

Background Elements, the fib Class, and CSS Defaults

The `.fi` class is designed for empty `<span>` elements. For applying a flag as a background image to any other element (a `<div>`, a `<button>`, or a custom component), the README recommends using `.fib` in place of `.fi`. The background approach relies on these CSS properties, which the library applies:

background-size: contain;
background-position: 50%;
background-repeat: no-repeat;

Because `background-size: contain` places the flag in the centre of the element at its maximum size without cropping, the element's dimensions must be set manually. The README specifies a 4:3 ratio for standard flags and `flag-icon-squared` for square variants.

For the SASS integration path, import the library and optionally override configuration variables:

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

The `$flag-icons-included-countries` variable is the key tool for bundle size control: by listing only the country codes the project uses, the output CSS includes only those flag definitions. The full list of configurable variables is in `sass/_variables.scss`.

Building Locally and Customizing the CSS Output

The repository uses Sass to compile the flag CSS from SCSS source files. Clone the repository, install dependencies with yarn, then build the CSS:

$ yarn build

This runs two Sass compilations from `sass/flag-icons.scss`: a development build (`css/flag-icons.css`) and a minified production build (`css/flag-icons.min.css`).

To preview the flag collection in a browser:

$ yarn start

This serves the project at `localhost:8000` using `http-server`.

To produce a CSS file that includes only a subset of countries, the README instructs removing the unwanted entries from `sass/_flag-icons-list.scss` and running `yarn build` again. This approach is lower-level than the SASS configuration variable but produces the same outcome: a smaller CSS file.

The package.json `scripts` section also exposes `svgo:all` and `svgo:min` targets for re-optimising SVG files using SVGO, and an `ids` target that regenerates the flag IDs list from the Python script `flag-ids.py`.

Limitations and What the Package Does Not Cover

flag-icons covers countries with ISO 3166-1-alpha-2 codes, which is the international standard for sovereign countries. It does not include flags for disputed territories, historical nations, regional flags, or flags of organisations unless those appear in the ISO list. The demo at flagicons.lipis.dev shows the complete set.

The package provides only the visual assets and CSS. It does not include a React component, a Vue component, or any JavaScript logic. The related searches show demand for a React integration (`flag icons react`), which requires the developer to wrap the CSS classes in a component themselves, or to use a third-party wrapper package that builds on flag-icons as a peer dependency.

SVG files are rendered by the browser. In contexts where image rendering is disabled or where the page is being consumed by a screen reader, the flags display as empty elements without accessible alternative text. Developers who need accessible flag elements must add `aria-label` attributes manually when using the `<span>` approach.

The PNG format is not provided. The related searches show demand for `flag icons png`. Teams that need PNG files for contexts where SVG is not supported (such as some email clients or older applications) must convert from the provided SVG source files.

React Integration and Third-Party Wrappers

The related searches show that many developers want to use flag-icons in a React application. The flag-icons package itself is framework-agnostic, but the CSS class approach works in React directly: load the CSS once in the application entry point, then render `<span className="fi fi-de">` in any component.

Note the attribute difference: HTML uses `class`, while JSX uses `className`. The `fis` class for squared flags is appended the same way: `<span className="fi fi-de fis">`. No additional package is required beyond the CSS import.

For teams who prefer a purpose-built component API, there are third-party React wrapper packages on npm that wrap this library's CSS, though those are separate projects from the flag-icons repository and are not maintained by the same author. The flag-icons package at v7.5.0 is the canonical source of the SVG assets and CSS that those wrappers depend on.

Editorial conclusion

flag-icons is the right choice for any web project that needs to display country flags inline with text or as background images using standard CSS classes. It covers every country in the ISO 3166-1-alpha-2 standard and the SASS configuration lets teams bundle only the flags they need. The last push to the repository was on 10 July 2026, and the most recent release is v7.5.0. The MIT licence allows use in commercial projects without restriction.

Frequently asked questions

Official sources

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