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, remember to set useCssModules to false (unfortunately create-react-app does not currently support Css modules).

import FlagIconFactory from 'react-flag-icon-css'

const FlagIcon = FlagIconFactory(React, { useCssModules: false })
// ...

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

import React from 'react'
import ReactDOM from 'react-dom'
import FlagIconFactory from 'react-flag-icon-css'

const FlagIcon = FlagIconFactory(React)
// If you are not using css modules, write the following:
// const FlagIcon = FlagIconFactory(React, { useCssModules: false })

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.

Configuration for Facebook's Flow

You can skip this section if you are not using Flow in your project.

The following are the rules that you need in your .flowconfig:

[options]
...
# Used in tests.
suppress_comment=\\(.\\|\n\\)*\\$FlowExpectError
suppress_comment=\\(.\\|\n\\)*\\$FlowFixMe
# SEE: https://github.com/facebook/flow/issues/1895
suppress_type=$FlowIssue
...
[ignore]
...
# SEE: https://github.com/stylelint/stylelint/issues/2322
.*/node_modules/stylelint/.*
...

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 */
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.19 (2017-07-02)

• docs(github): add 'css-loader' request (fdd3cbe)
• docs(README): add 'className' and 'styleName' to props (ae27154)
• docs(README): fix named import (1d15ca4)
• docs(README): replace '<code>' with backtick, misc updates (0540064)
• test: add new tests, 'snapshot tests', 'react-test-renderer' (945e7b7)
• test: update ava snapshots .snap (19fe4f1)
• test: upgrade ava to v.0.2.0, refactor and add new tests (16390b2)
• chore: remove 'jsdom' as it is unused atm (b32b7ba)
• chore(package): add 'package-lock.json' and regenerate lock files (f854fb6)
• chore(package): bump 'chalk', 'eslint-plugin-jsx-a11y', fix 'jsdom' version (9b77371)
• chore(package): run finepack (114dbc0)
• chore(package): update nyc to version 11.0.1 (2fbbee6)
• chore(package): upgrade cross-env to version 5.0.1 (b210795)
• chore(package): upgrade flow-bin to version 0.49.1 (95104f3)
• chore(package): upgrade prettier to version 1.4.2 (71822d0)
• chore(package): upgrade prettier to version 1.4.4 (b618a19)
• chore(test): move functions used by tests to 'internals' (52004bd)
• chore(travis): add Node.js 8 (b71d5a6)
• refactor: remove dependency on 'react-css-modules' (c51ecf6)
• refactor: remove unused 'objectKeysApplyFn' and move 'diffArrays' (67910cc)
• refactor(test): move static data to 'static' folder (b9037a7)
• fix: add 'className' and 'styleName' to prop-types (e3dac5a)
• fix: correct global 'className' handling (3123449)

<a name="1.0.18"></a>