Guide · Open source

How to use flag-icons: add country flags to your website

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

flag-icons is an open-source collection of SVG country flags, paired with CSS that makes them easy to place on a web page. This guide shows how to install it, load the styles, and display flags next to country names using ISO 3166-1 alpha-2 codes. By the end you will be able to add a flag to any page and trim the CSS to only the countries you need.

flag-iconslipis/flag-icons · ★ 12.5k · MIT Install options & downloads

Quick start

1Install the package. Run npm install flag-icons or yarn add flag-icons in your project folder.
2Load the stylesheet. Import css/flag-icons.min.css from node_modules, or add the CDN link tag to your HTML head.
3Pick the country code. Find the ISO 3166-1 alpha-2 code for the country you need, such as gr for Greece.
4Add the classes to a span. Place fi and fi-gr on an empty span to show the flag inline with text.
5Make it squared if needed. Add the fis class to the span for a squared flag.
6Optionally trim the CSS. Use the SASS module with $flag-icons-included-countries to include only the flags you use.

What flag-icons includes and who it suits

flag-icons is a set of assets and styles, not a program. It provides SVG images of country flags and CSS that makes them simple to add to a website. It is mainly useful for web projects that show flags next to country names or in lists.

It fits web developers who need flags in a site or app, teams that want one consistent flag style without sourcing images themselves, and projects that prefer loading styles from a CDN without installing anything.

Best for: web projects that show flags next to country names or in lists
Best for: projects that only need a subset of flags and want smaller CSS using SASS settings
Not for: mobile apps that need PNG flag images, since the README covers SVG and CSS only

Install flag-icons with npm or Yarn

You can download the whole project as is, or install it with a package manager. Installing via npm or Yarn requires Node.js or Yarn respectively. If you skip the package manager, you can use the CDN method in the next section instead.

Prerequisites: Node.js or Yarn (only if installing via npm or Yarn)

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

Load the flag-icons CSS in your page

Before any flag appears, the stylesheet has to be loaded. The README gives three options: import the CSS from node_modules, link the CDN file, or import the SASS module into your own stylesheet.

The SASS option lets you override the path to the flags directory and list only the countries you want. Variables are defined in sass/_variables.scss.

JavaScript import from node_modules: css/flag-icons.min.css
CDN: the jsDelivr link to css/flag-icons.min.css, pinned to a release tag
SASS: @use the flag-icons module, optionally with $flag-icons-included-countries

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

Add a flag to an empty span

Add the class fi and a class fi-xx to an empty span, where xx is the ISO 3166-1 alpha-2 code of the country. For example, fi-gr shows the flag of Greece. To get a squared flag, also add the class fis.

You can also apply the classes to other elements, but then use fib instead of fi. The flag is placed in the middle of the element at its natural ratio only if you set the size yourself: the README suggests a 4 by 3 ratio, or the flag-icon-squared class for square flags.

fi fi-xx: standard flag inside an empty span
fi fi-xx fis: squared version of the flag
fib fi-xx: for use on any other element, with manual sizing required

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

Trim the CSS to the countries you need

If your project only uses a few flags, you can limit the output. Set the $flag-icons-included-countries list in the SASS configuration, or edit that list in sass/_variables.scss and rebuild.

The README also explains how to run yarn to install dependencies after cloning, yarn build to build the SCSS files, and yarn start to serve the project on localhost:8000.

Set $flag-icons-included-countries to a list such as ("gr", "de", "gb")
Set $flag-icons-path to override where the flags directory is read from

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

What people use it for

Showing a flag beside each country name in a country picker or form
Adding flags to a list of countries on a directory or data table
Displaying a consistent flag style across a website without sourcing images yourself
Reducing stylesheet size by including only a handful of countries via SASS

Frequently asked questions

How do I install flag-icons?

Run npm install flag-icons or yarn add flag-icons in your project. You can also download the whole project from the repository as a zip file. Installing with npm or Yarn requires Node.js or Yarn.

Do I need Node.js to use flag-icons?

Only if you install it via npm or Yarn. The README also offers a CDN link and a direct download, so you can use the CSS without a package manager.

How do I choose the right flag code?

Use the ISO 3166-1 alpha-2 code of the country, such as gr for Greece or gb for the United Kingdom, and add it as fi-xx to the class list. The README links to the ISO search page for codes.

Why does my flag not show or appear at the wrong size?

Check that the stylesheet is loaded and that the span is empty, as the README describes. If you used fib on another element, the flag only appears at the size you set, since the README suggests a 4 by 3 ratio.

Is flag-icons free to use and what is its licence?

The project is licensed under MIT. The README credits koppi's earlier SVG flag collection, which is now deleted, as the origin of the work.

Can I use flag-icons for a mobile app?

The README covers SVG and CSS only, so it does not provide PNG flags for mobile apps. For those projects, look for a source that offers non-web formats.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

flag-icons suits web developers who want consistent SVG country flags with simple CSS classes, especially if they want to load it from a CDN or trim it with SASS. It is not a ready-made app, and projects that need PNG flags for mobile apps should pick a different option, such as one of the comparable projects listed in the directory.

Install options & downloads