react-flag-icon-css

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

Installation

React Flag Icon Css is distributed as an npm package.

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

$ yarn add react-flag-icon-css

or with npm ¹:

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

¹ 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 (unfortunately create-react-app does not currently support Css modules).

Prerequisites for custom apps

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

If you are using webpack, you will need to install and configure a few commmonly used modules (see the webpack 2 example project):

$ 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 = {}) =>
  <div>
    <FlagIcon code={props.code} size={props.size} />
  </div>

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

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

A webpack 2 example project is available.

:flags: FlagIcon props

The entries marked with * 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.

¹ Upgrade to version 1.0.17 or later of this module.

:factory: FlagIconFactory

The entries marked with * are required.

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

:factory: 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. Example.
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.

² 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.57.3.

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
    |--index.js
    |--istyles.css
    |--images
       |--1x1
          |--ex1.svg
          |--ex2.svg
          |--ex3.svg
       |--4x3
          |--ex1.svg
          |--ex2.svg
          |--ex3.svg

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.

Development

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.

Contributing

Contributions are welcome:

• :pencil2: 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.

• :bug: 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.

• :triangular_ruler: 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! :blue_heart:

Find this module useful?

:star: 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.

License

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

Changelog

1.0.23 (2017-10-29)

• docs(README): improve docs and remove duplication (054c601)
• fix(flow): use (placeholder) type for React module, fix/improve docs (360ca47)
• chore(bumped): add lockfile generation and commit (543be4c)
• chore(package): update lockfiles (33f32d7)

<a name="1.0.22"></a>