country-flag-icons

What is country-flag-icons?

The country-flag-icons npm package provides a collection of SVG country flags that can be easily integrated into web applications. It allows developers to display country flags by using simple class names.

What are country-flag-icons's main functionalities?

Display a country flag

This feature allows you to display the flag of a specific country by using a class name. In this example, the flag of the United States is displayed.

<i class='flag-icon flag-icon-us'></i>

Change flag size

This feature allows you to change the size and shape of the flag. In this example, the flag of the United States is displayed in a squared format.

<i class='flag-icon flag-icon-us flag-icon-squared'></i>

Use with different frameworks

The package can be used with various front-end frameworks like React, Angular, and Vue. The code sample shows how to use it in a plain HTML setup, but it can be easily adapted for other frameworks.

<i class='flag-icon flag-icon-us'></i>

Other packages similar to country-flag-icons

flag-icon-css

The flag-icon-css package provides a similar collection of SVG country flags that can be used in web applications. It offers a wide range of flags and is highly customizable. Compared to country-flag-icons, flag-icon-css has a larger community and more frequent updates.

react-world-flags

The react-world-flags package is specifically designed for React applications. It provides a set of country flags as React components, making it easy to integrate into React projects. Unlike country-flag-icons, this package is tailored for React and offers better integration with React's component-based architecture.

world-flags-sprite

The world-flags-sprite package offers a sprite sheet of country flags, which can be used to display flags by specifying the position in the sprite. This approach can be more efficient in terms of loading times compared to individual SVG files. However, it may require more effort to set up and use compared to country-flag-icons.

README

country-flag-icons

Vector country flag icons in 3:2 aspect ratio.

• Optimized for small size on screen (little detail, minimalism).
• Small file size.
• Comes with React components for all flags (exported from /react subpackage).

See 3:2 flags

Install

npm install country-flag-icons --save

API

hasFlag(country: string): boolean

Tells whether there's a flag for a country.

import { hasFlag } from 'country-flag-icons'

hasFlag('US') === true
hasFlag('ZZ') === false

countries: string[]

The list of supported countries.

import { countries } from 'country-flag-icons'

countries.includes('US') === true
countries.includes('ZZ') === false

Web

Flags can be linked directly from this library's gitlab pages website, or from a github pages mirror, which seems a tiny bit faster.

<img
  alt="United States"
  src="http://purecatamphetamine.github.io/country-flag-icons/3x2/US.svg"/>

Flags can also be used in the form of CSS classes imported from country-flag-icons/3x2/flags.css where all flag icons are inlined as background-image data URLs. CSS flag icon height can be set via --CountryFlagIcon-height CSS variable.

What if my project doesn't use CSS variables?

In that case, the default flag icon height is 1em, and to change it, just set a font-size:

/* Set flag icon height to 24px. */
[class*=' flag:'], [class^='flag:'] {
  font-size: 24px;
}

Unicode

Unicode flag icons are available under the /unicode export.

import getUnicodeFlagIcon from 'country-flag-icons/unicode'

getUnicodeFlagIcon('US') === '🇺🇸'
getUnicodeFlagIcon('ZZ') === '🇿🇿'

Unicode flag icons ("Regional Indicator Symbols") were introduced in 2010 in Unicode version 6.0.

Older operating systems might not support Unicode flags, either rendering "missing" (rectangle) characters (if their system doesn't support country flags), or displaying two-letter country codes instead of emoji flag images. For example, Windows 10 currently (01.01.2020) doesn't support Unicode country flags, and displays two-letter country codes instead of emoji flag images.

React

React components for all flags are available at /react/3x2 export.

import { US } from 'country-flag-icons/react/3x2'

<US title="United States" className="..."/>

Or directly, if your bundler doesn't support tree shaking:

import US from 'country-flag-icons/react/3x2/US'

<US title="United States" className="..."/>

Vue

There's an experimental component for Vue 3.

String

All flags can also be imported as strings:

import { US } from 'country-flag-icons/string/3x2'

console.log(US) // > '<svg xmlns="http://www.w3.org/2000/svg" ...</svg>'

Or directly, if your bundler doesn't support tree shaking:

import US from 'country-flag-icons/string/3x2/US'

console.log(US) // > '<svg xmlns="http://www.w3.org/2000/svg" ...'

Criteria for inclusion

See Criteria for inclusion section on the ISO-3166-1 standard Wikipedia page.

This library includes the flags for all countries, territories, or areas of geographical interest that have an officially assigned code in the ISO-3166-1 standard.

Additionally, this library includes a European Union (EU) flag because it's part of the "exceptional reservations" of the ISO-3166-1 standard and there have been requests to do so.

So, the full list is all of the 249 officially assigned ISO-3166-1 codes, plus:

• AC — Ascension Island. Exceptional reservation. Has it's own phone numbering plan.
• TA — Tristan da Cunha. Exceptional reservation. Has it's own phone numbering plan.
• IC — Canary Islands. Exceptional reservation. Doesn't have its own phone numbering plan.
• EU — European Union. Exceptional reservation. Doesn't have its own phone numbering plan.
• XK — Kosovo. Disputed territory. Not an officially assigned code. Has it's own phone numbering plan.

GitHub

On March 9th, 2020, GitHub, Inc. silently banned my account (erasing all my repos, issues and comments) without any notice or explanation. Because of that, all source codes had to be promptly moved to GitLab. The GitHub repo is now only used as a backup (you can star the repo there too), and the primary repo is now the GitLab one. Issues can be reported in any repo.

Alternatives

• FlagKit (flagpack npm package) — 4x3 and 1x1 SVG flag icons. MIT licence.

Credits

I used Google image search for flag references, and various country flag packs (including FlagKit / flagpack) for design ideas. Sometimes there was no need to re-draw a flag — usually in cases when a flag is just a set of colored stripes and there already is an SVG version of it somewhere at Wikipedia or some other free flag pack, so in those cases I simply copied those flags (because they look the same in every flag pack).

Some countries officially use their "mother" country flag (those used to be colonies). For example, BV (Bouvet Island) and SJ (Svalbard and Jan Mayen) use the flag of Norway; GP (Guadeloupe) and RE (Réunion) use the flag of France.

CSS flag icons feature has been submitted by @mindplay-dk.