Skip to content
Simple React SVG country flags Component, supports standard Css and Css Modules.
JavaScript CSS
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github docs(github): add 'css-loader' request Jul 8, 2017
src chore: upgrade 'babel' to version 7, 'ava' to version 1, 'react' and … Jan 16, 2019
.eslintignore fix(eslint): correct lib ignore path Oct 29, 2017
.npmignore fix: remove flow folders and hidden files from release bundle shipped… Jul 16, 2018
.travis.yml Release 1.0.25 Jan 16, 2019
package-lock.json chore(package): update lockfile package-lock.json Jan 28, 2019

A simple React SVG country flags component: it works with Css Modules (default) or standard Css.

NPM version NPM downloads license Build Status Greenkeeper badge dependencies Status devDependencies Status peerDependencies Status codecov Coverage Status


React Flag Icon Css is distributed as an npm package.

We recommend installing and managing npm packages with yarn or npm 6:

$ yarn add react-flag-icon-css

or with npm 1:

$ npm install --save react-flag-icon-css

1 You can omit --save if using npm >= 5.

Using in a create-react-app app

Apps bootstrapped with create-react-app support this module out of the box, just follow the Basic Usage example and remember to set useCssModules to false (create-react-app does not currently support Css modules in its stable version, you can try the alpha but it will still not work with this module).

Prerequisites for custom apps

We recommend using the webpack 4 module bundler and ecosystem to assemble your app, even though this module works with webpack >= 1 and should also work with other bundlers.

If you are using webpack, you will need to install and configure a few commmonly used modules - see the webpack 4 example project (also available for: webpack 3, webpack 2, and webpack 1).

$ yarn add -D babel-loader css-loader file-loader style-loader extract-text-webpack-plugin

or with npm:

$ npm install --save-dev ...

Basic usage

Import FlagIconFactory from react-flag-icon-css, it accepts the React module as the first argument and creates the FlagIcon component (remove the @flow comment if you don't use Flow, it does not have any effect). This approach ensures that FlagIcon uses your app's React instance, avoiding issues such as two versions of React being loaded at the same time.

/* your-app/your-components-directory/FlagIcon.js */
// @flow
import * as React from 'react'
import FlagIconFactory from 'react-flag-icon-css'

// Please only use `FlagIconFactory` one time in your application, there is no
// need to use it multiple times (it would slow down your app). You may place the
// line below in a `FlagIcon.js` file in your 'components' directory, then
// write `export default FlagIcon` as shown below and import it elsewhere in your app.
const FlagIcon = FlagIconFactory(React)
// If you are not using css modules, write the following:
// const FlagIcon = FlagIconFactory(React, { useCssModules: false })

export default FlagIcon
/* your-app/App.js */
// @flow
import * as React from 'react';
import ReactDOM from 'react-dom'
import FlagIcon from './your-components-directory/FlagIcon.js'

const App = (props = {}) =>
    <FlagIcon code={props.code} size={props.size} />

const rootEL = document.body.querySelector('#app')

const appProps = { code: 'it', size: '3x' }
ReactDOM.render(<App {...appProps} />, rootEL)

A webpack 3 example project is available (webpack 2 and webpack 1 versions).

🎏 FlagIcon props

The entries marked with &ast; are required.

Prop Type Flow Type Default Description Supported values
code * String FlagIconCodeType 1 ISO 3166-1-alpha-2 code. The list is here.
size String FlagIconSizeType lg, 2x, 3x, 4x, 5x
flip String FlagIconFlipType horizontal, vertical
rotate Number FlagIconRotateType 30, 60, 90, 180, 270
squared Boolean boolean false Uses the 1x1 image if true.
Component String string span e.g span, div
className String string This is always appended as-is to class in the HTML. e.g some-class
styleName String string This is mapped to a CSS module and appended to class in
the HTML.
e.g some-class
Children String React$Element<*> React element. e.g <Something />

Remember to always build FlagIcon with FlagIconFactory.

1 Upgrade to version 1.0.17 or later of this module.

🏭 FlagIconFactory

The entries marked with &ast; are required.

Argument Type Flow Type Description Supported values
React * Module ReactModule Your app's React instance. Versions in peerDependencies.
options Object FlagIconOptionsType See FlagIconFactory options below.

🏭 FlagIconFactory options

Argument Type Flow Type Description Supported values Default
useCssModules Boolean Boolean Use CSS modules styles (your module bundler must be correctly setup). true, false true
customCodes 2 Object Object An object literal whose keys are your custom codes.
themeStyles Object CssModule Set this if useCssModules is true and a) you want to apply styles to FlagIcon
using .theme-base and/or
b) you are using custom flags.

2 Upgrade to version 1.0.17 or later of this module.

Facebook's Flow support

This module has 0 Flow errors on flow-bin version: ^0.76.0.

If in your app you are using a Flow version that is the same or newer than that, you should not need any specific configuration excluding the installation of the flow-typed definition for prop-types (you may also take the opportunity to install definitions for all your app's modules using flow-typed).

However, if in your app you are using a newer or particularly older version (not recommended) of Flow, it may throw warnings or errors. Please open an issue or submit a pull request if this module has not yet been made compatible with a newer Flow version.

Custom flags

Required parameters

  • Always set FlagIconFactory options.customCodes to make this module aware of your codes. Otherwise: runtime warnings in development (and Flow errors, if you use it).
  • If using Css Modules, import your styles in someVariable and set FlagIconFactory options.themeStyles to someVariable. Otherwise: runtime Css Modules errors.
  • Else if using standard Css, make sure to import the styles. Otherwise: the custom images won't be loaded.
  • If using Flow use CustomFlagIconFactory and not FlagIconFactory. Otherwise: Flow errors.

Quick example

We recommend organizing your custom flags in a folder similar to example-custom-flags. You may copy-paste it in the root of your app and replace the codes and images.

Example folder structure:

|-- app.js
|-- example-custom-flags

Write the styles for each one of your codes, and load the appropriate images:

/* example-custom-flags/styles.css */
 * Note: you can use PostCSS, SASS or whatever preprocessor your
 * app is using here.
.flag-icon-ex1 {
  background-image: url(../images/4x3/ex1.svg);

.flag-icon-ex1.flag-icon-squared {
  background-image: url(../images/1x1/ex1.svg);

/* ... */

Import the styles and export them and the object with your codes:

/* example-custom-flags/index.js */
import styles from './styles.css'

const codes = {
  ex1: 'Example 1 country',
  ex2: 'Example 2 country',
  ex3: 'Example 3 country',

// You can comment or remove the following line if you don't use Facebook's Flow.
export type CustomCodeType = $Keys<typeof codes>

export { styles, codes }

Import CustomFlagIconFactory in your app and build FlagIcon as shown:

/* app.js */
// @flow
import React from 'react'
import { CustomFlagIconFactory } from 'react-flag-icon-css'
import { styles, codes } from './my-custom-flags'

// Using 'react-css-modules'? Use this:
const optionsCssModules = { customCodes: codes, themeStyles: styles }
const FlagIconCssModules = CustomFlagIconFactory(React, optionsCssModules)

// Using global CSS? Use this instead:
const options = { useCssModules: false, customCodes: codes }
const FlagIcon = CustomFlagIconFactory(React, options)

Note: when you build FlagIcon with CustomFlagIconFactory, it can be used with both built-in and custom codes.


Runtime type checking: in development mode (process.env.NODE_ENV !== 'production'), when using unsupported props or prop values, you are warned at runtime by Failed prop type errors in the browser console. Feature powered by prop-types.

Static type checking:

If you use Facebook's flow in your app (otherwise you can skip this section, unless you want to submit a pull request), it should automatically pick up this package's definitions from the .js.flow files that are distributed with it, checking your code accordingly when you run yarn flow. Using the latest Flow version or the version in ./package.json is recommended. We also recommend using a Flow-aware editor such as Nuclide for Atom.

If you use Microsoft's TypeScript in your app (otherwise you can skip this section, unless you want to submit a pull request), the package that contains the type definitions for this module is: @types/react-flag-icon-css.


Contributions are welcome:

  • ✏️ Write code: use a topic branch, follow the AngularJS commit style guidelines and check that yarn prepublish (build, test, type checking, linting ...) returns zero errors before opening a PR. If you want to make major modifications to the code, please open an issue to discuss them first.

  • 🐛 Report a bug: first, search all issues. If nothing turns up, open a new issue and be as specific as possible, so that we can reproduce your setup and find out if it is a bug or a configuration issue.

  • 📐 Propose a feature: first, search all issues. If nothing turns up, open a new issue and describe what the proposed feature should do, why you think it is important and an example use case.

Thanks! 💙

Find this module useful?

⭐️ Starring it lets you keep track of this project and helps more people discover it.

Source of the flags

This project uses the great SVG country flags from flag-icon-css.


This project is licensed under the terms of the MIT license.

You can’t perform that action at this time.