React Country Flag Component

3.1.0 · active · verified Sun Apr 19

The `react-country-flag` package provides a React component designed for displaying country flags, offering flexibility through both emoji and SVG renditions. Currently stable at version `3.1.0`, this library is actively maintained, with its latest major update (v3) primarily focusing on introducing comprehensive TypeScript type definitions, enhancing developer experience without breaking changes from the previous major version. Earlier, `v2.x` introduced several breaking changes related to prop naming and accessibility responsibilities, which developers upgrading from `v1.x` should be aware of. A key differentiator is its ability to choose between emoji or SVG rendering, with support for custom SVG CDN configurations, allowing for highly customizable and performant flag display. It passes all standard HTML attributes to the underlying element, providing full control over styling and accessibility. While supporting emoji flags, the library also acknowledges potential cross-platform display inconsistencies and implicitly encourages developers to consider emoji support detection or to leverage its robust SVG rendering capabilities for maximum compatibility.

Common errors

```
TypeError: (0 , react_country_flag__WEBPACK_IMPORTED_MODULE_2__.default) is not a function
```
cause Attempting to import `ReactCountryFlag` as a named export when it is a default export in the package.

fix Change `import { ReactCountryFlag } from 'react-country-flag'` to `import ReactCountryFlag from 'react-country-flag'`.
```
Property 'code' does not exist on type 'ReactCountryFlagProps'. Did you mean 'countryCode'?
```
cause Using the deprecated `code` prop instead of the updated `countryCode` prop, which was a breaking change in v2.0.0.

fix Update the prop from `code="US"` to `countryCode="US"`.
```
Flags are not showing up or appear as blank squares in the browser.
```
cause This often occurs when emoji flags are used on a system or browser that lacks sufficient emoji font support, or if there's an issue with the `cdnUrl` or `cdnSuffix` when using SVG flags.

fix If using emoji flags, verify emoji support on the target system/browser or switch to SVG flags by adding the `svg` prop. If using SVG flags with a custom CDN, double-check that `cdnUrl` and `cdnSuffix` are correctly configured and accessible.

Warnings

breaking The prop `code` was renamed to `countryCode`. Using `code` will no longer work and may result in a TypeScript error or unhandled prop.
Fix: Replace `code="GB"` with `countryCode="GB"`.
breaking The default `title` and `aria-label` attributes for accessibility were removed. Developers are now responsible for passing these props explicitly.
Fix: Add `title="United States"` and/or `aria-label="United States"` props directly to the `ReactCountryFlag` component for improved accessibility.
breaking The prop `styleProps` was renamed to `style` to align with standard React prop naming conventions.
Fix: Change `styleProps={{ fontSize: '2em' }}` to `style={{ fontSize: '2em' }}`.
gotcha Emoji flags (`svg` prop not used) may not display consistently across all browsers and operating systems due to varying emoji font support.
Fix: For critical applications, consider explicitly using the `svg` prop (`<ReactCountryFlag countryCode="US" svg />`) or implement client-side emoji support detection (e.g., using `detect-emoji-support`) to conditionally render SVG flags.

Install

npm install react-country-flag npm
yarn add react-country-flag yarn
pnpm add react-country-flag pnpm

Imports

ReactCountryFlag
wrong:
```
import { ReactCountryFlag } from 'react-country-flag'
```
correct:
```
import ReactCountryFlag from 'react-country-flag'
```
The primary component is exported as a default export, not a named export. Importing with curly braces will lead to runtime errors.
ReactCountryFlag (CommonJS)
```
const ReactCountryFlag = require('react-country-flag')
```
For CommonJS environments, use `require()` to import the default export.
ReactCountryFlagProps
wrong:
```
import { ReactCountryFlagProps } from 'react-country-flag'
```
correct:
```
import type { ReactCountryFlagProps } from 'react-country-flag'
```
Import the component's TypeScript prop types using `import type` for type-checking without bundling value imports.

Quickstart

Demonstrates basic usage of the `ReactCountryFlag` component, showcasing both emoji and SVG rendering options, along with custom styling and accessibility attributes.

import React from "react"
import ReactCountryFlag from "react-country-flag"

function ExampleComponent() {
    return (
        <div>
            <ReactCountryFlag countryCode="US" />

            <ReactCountryFlag
                className="emojiFlag"
                countryCode="US"
                style={{
                    fontSize: '2em',
                    lineHeight: '2em',
                }}
                aria-label="United States"
            />

            <ReactCountryFlag countryCode="US" svg />

            <ReactCountryFlag
                countryCode="US"
                svg
                style={{
                    width: '2em',
                    height: '2em',
                }}
                title="US"
            />

            <ReactCountryFlag
                countryCode="US"
                svg
                cdnUrl="https://cdnjs.cloudflare.com/ajax/libs/flag-icon-css/3.4.3/flags/1x1/"
                cdnSuffix="svg"
                title="US"
            />
        </div>
    )
}

export default ExampleComponent

view raw JSON →