Repository of all ISO3166-1 and ISO3166-2 flags

A comprehensive library of all ISO3166-1 & ISO3166-2 country/subdivision codes and their corresponding flag icons in SVG format. View demo here (repo).

iso3166-flag-icons is a comprehensive repository of all ISO 3166-1 and ISO 3166-2 flag icons according to the International Organisation for Standard that defines codes for the names of countries, dependent territories, special areas of geographical interest, and their principal subdivisions [1]. The repo contains 266 ISO3166-1 alpha-2 flag icons and over 3200 ISO3166-2 flags.

The ISO 3166-1 icons are those of the names of countries and their subdivisions that can be broken into three sets of country codes:

• ISO 3166-1 alpha-2 – two-letter country codes which are the most widely used of the three, and used most prominently for the Internet's country code top-level domains (with a few exceptions).
• ISO 3166-1 alpha-3 – three-letter country codes which allow a better visual association between the codes and the country names than the alpha-2 codes.
• ISO 3166-1 numeric – three-digit country codes which are identical to those developed and maintained by the United Nations Statistics Division, with the advantage of script (writing system) independence, and hence useful for people or systems using non-Latin scripts.

The ISO 3166-2 icons are those of the names of countries and their subdivisions – Part 2: Country subdivision code, defines codes for the names of the principal subdivisions (e.g., provinces, states, departments, regions) of all countries coded in ISO 3166-1 [2].

The ISO 3166-3 icons are those of countries and their subdivisions – Part 3: Code for formerly used names of countries, defines codes for country names which have been deleted from ISO 3166-1 since its first publication in 1974.

Table of Contents

• Motivation
• Usage
• Requirements
• Installation
• Directory Folders
• Open Issues
• Contact
• License
• References

Motivation

The main motivation behind this project was to integrate additional flag icons into my custom-built web-app Flagle (https://flagle.vercel.app/). This daily worldle-inspired game generates a new flag from around the world each day, consisting of flags of countries, territories and everywhere in between.

After searching around, it was fairly straightforward to find a repo with ISO 3166-1 flags, an example being here but there didn't seem to be any single repo/dataset of all ISO 3166-2 subdivision flags, hence I decided to make one from scratch.

Installation

A zipped folder of all ISO 3166-1 OR ISO 3166-2 flag icons are available to download in the /downloads folder of the repo.

The whole project can be cloned from git:

git clone https://github.com/amckenna41/iso3166-flag-icons.git

The ISO 3166-1 and ISO 3166-2 are also split into branches and be downloaded seperately:

git clone -b iso3166-1-icons https://github.com/amckenna41/iso3166-flag-icons.git 
OR
git clone -b iso3166-2-icons https://github.com/amckenna41/iso3166-flag-icons.git 

Install via npm or yarn (not implemented yet):

npm install --dev iso3166-flag-icons

yarn add --dev iso3166-flag-icons

Usage

The flags can be implemented in-line by referencing the CSS class of the respective flag using the ISO 3166-1 or ISO 3166-2 CSS file. For ISO 3166-1 icons add the classes .fi and .fi-xx (where xx is the ISO 3166-1-alpha-2 code [5] of a country) to an empty <span>. To add a squared version flag then additionally add the class fis. Example:

1<span class="fi fi-ad"></span> <span class="fi fi-ad fis"></span>

For ISO 3166-2 icons add the classes .fi and .fi-xx-yy (where xx is the ISO 3166-1-alpha-2 code [2] of a country and yy is the ISO 3166-2 code, both in lower-case) to an empty <span>. For example to import the flag for the Canillo Parish of Andorra:

1<span class="fi fi-ad-02"></span> <span class="fi fi-ad-02 fis"></span>

Folders and files

• /iso3166-1-icons - flags of all country/territories/subdivisions according to the ISO 3166-1 standard [5].
• /iso3166-2-icons - flags of all subdivisions within countries/territories according to the ISO 3166-2 standard [2].
• /scripts - various Python and bash scripts created for downloading and compressing all the required flag SVG files for both the ISO 3166-1 and ISO 3166-2 icons, as well as scripts for creating the json, CSS and readme files.
• /downloads - directory of zipped iso3166-1 and iso3166-2 flag icons files.
• /css - css scripts for integrating the flags into front-end projects.
• index.html - front-end demo for iso3166-flag-icons repo.
• iso3166-1.json - json containing all ISO 3166-1 country names, 2 letter codes and relative path to flag icon in repo.
• iso3166-2.json - json containing all ISO 3166-2 country names, 2 letter codes, all subdivision codes and common names as well as all info pulled per country via the restcountries api (https://restcountries.com/).
• iso3166-2-min.json - minimised json containing all ISO 3166-2 country names, 2 letter codes and all subdivision codes and common names.

Issues

Due to the nature of the methodology for getting the ISO 3166-2 subdivision flags, as well as the verbosity of flags included, there may exist several outstanding issues with the existing flag icons. A list of countrys that have no recognised subdivisions and hence no flags in iso3166-2 is listed in the file scripts/iso3166-files/noISO3166-2Flags.csv. Another outstanding issue is some ISO3166-2 flags not having an existing or easily accessible SVG version of their flag hence some flags are in png/jpg/gif format. Please feel free to do a PR if SVG versions of these flags become available.

Please feel free to raise an Issue in the Issues tab if any incorrect/missing subdivision flags as well as any errors/bugs are found

Contact

If you have any questions or feedback, please contact amckenna41@qub.ac.uk or visit my LinkedIn:

License

Distributed under the MIT License. See LICENSE for more details.

References

[1]: https://en.wikipedia.org/wiki/ISO_3166
[2]: https://en.wikipedia.org/wiki/ISO_3166-2
[3]: https://github.com/lipis/flag-icons
[4]: https://github.com/amckenna41/flagle
[5]: https://en.wikipedia.org/wiki/ISO_3166-1

Back to top