National Flag Icons for React (v2.0.0)

A React component library that displays flag icons based on ISO-2 country codes.

Version 2.0 Updates:

• ✨ Updated to React 18
• 🔧 Replaced deprecated zoom CSS property with transform: scale() for better cross-browser compatibility
• 📦 Updated to modern dependency versions
• 💎 Improved code quality with TypeScript best practices
• 🎯 Single source of truth for flag codes to prevent inconsistencies

Installation

npm install national-flag-icons
# or
yarn add national-flag-icons

Usage

Basic Usage (JavaScript)

import React from 'react';
import Flag from 'national-flag-icons';

const App = () => {
  return (
    <Flag flagCode="us" height={25} />
  );
};

export default App;

TypeScript Usage

import React from 'react';
import Flag from 'national-flag-icons';
import type { flagCodeType } from 'national-flag-icons';

type MyProps = {
  language: string;
  flag: string;
};

const LanguageSelector = (props: MyProps) => {
  const flagCode = props.flag as flagCodeType;
  const sizeY: number = 30;
  
  return (
    <>
      <span>{props.language}</span>
      <Flag flagCode={flagCode} height={sizeY} />
    </>
  );
};

export default LanguageSelector;

Note: The TypeScript example demonstrates type-safe usage when the flag code comes from a string variable.

Component Properties

| Property | Type | Required | Default | Description | |----------|------|----------|---------|-------------| | flagCode | flagCodeType | Yes | - | ISO-2 country code (e.g., "us", "gb", "fr"). Important: Language codes like "en" are invalid. Use country codes instead: "us" for USA, "gb" for Great Britain, or "au" for Australia. An error will be logged to the console if an invalid code is provided. | | className | string | No | "languageFlag" | Custom CSS class name for styling the component container. | | style | CSSProperties | No | undefined | React inline styles object for custom styling. Can override or extend default styles. | | height | number | No | 14 | Height of the flag in pixels. The flag will scale proportionally to maintain the correct aspect ratio. Default dimensions are 22×14 pixels (width×height). |

Available Flag Codes

All supported ISO-2 country codes: ad, at, bh, by, cm, dj, et, ge, gs, id, jm, kw, lu, ml, mw, nl, ph, re, sh, sy, tn, uy, ye, ae, au, bi, bz, cn, dk, eu, gf, gt, ie, jo, ky, lv, mm, mx, no, pk, ro, si, sz, to, uz, yt, af, aw, bj, ca, co, dm, fi, gg, gu, il, jp, kz, ly, mn, my, np, pl, rs, sj, tc, tr, va, za, ag, ax, bm, cc, cr, do, fj, gh, gw, im, ke, la, ma, mo, mz, nr, pm, ru, sk, td, tt, vc, zm, ai, az, bn, cd, cs, dz, fk, gi, gy, in, kg, lb, mc, mp, na, nu, pn, rw, sl, tf, tv, ve, zw, al, ba, bo, cf, cu, ec, fm, gl, hk, io, kh, lc, md, mq, nc, nz, pr, sa, sm, tg, tw, vg, am, bb, br, cg, cv, ee, fo, gm, hm, iq, ki, li, me, mr, nc2, om, ps, sb, sn, th, tz, vi, an, bd, bs, ch, cx, eg, fr, gn, hn, ir, km, lk, mf, ms, ne, pa, pt, sc, so, tj, ua, vn, ao, be, bt, ci, cy, eh, ga, gp, hr, is, kn, lr, mg, mt, nf, pe, pw, sd, sr, tk, ug, vu, ar, bf, bv, ck, cz, er, gb, gq, ht, it, kp, ls, mh, mu, ng, pf, py, se, st, tl, um, wf, as, bg, bw, cl, de, es, gd, gr, hu, je, kr, lt, mk, mv, ni, pg, qa, sg, sv, tm, us, ws

Example with All Properties

<Flag 
  flagCode="us" 
  height={25} 
  className="myCustomFlag" 
  style={{ boxShadow: "2px 2px 1px #9E9E9E" }} 
/>

Additional Exports

The package exports several useful types and constants:

| Export | Type | Description | |--------|------|-------------| | flagArray | readonly string[] | Array containing all valid flag codes. Useful for validation or creating dropdown menus. | | flagCodeType | type | TypeScript type definition representing all valid ISO-2 country codes as string literals. Provides autocomplete and type safety. | | flagProps | type | TypeScript interface for the Flag component props: { flagCode: flagCodeType; height?: number; style?: CSSProperties; className?: string; } |

Usage Example

import { flagArray, flagCodeType } from 'national-flag-icons';

// Validate a flag code
const isValidFlag = (code: string): boolean => {
  return flagArray.includes(code);
};

// Create a dropdown of all flags
const FlagSelector = () => (
  <select>
    {flagArray.map(code => (
      <option key={code} value={code}>{code}</option>
    ))}
  </select>
);

Alternative Component: Flag2

The package includes an alternative component Flag2 with different rendering characteristics.

Differences Between Flag and Flag2

| Feature | Flag (Default) | Flag2 (Alternative) | |---------|------------------|----------------------| | Structure | <div> with nested <img> element | Single <div> with background image | | Resizing | ✅ Fully scalable via height prop | ❌ Fixed at 22×14 pixels | | Use Case | General purpose, when sizing flexibility is needed | When you need minimal DOM structure and fixed size | | Technology | Image positioning | CSS sprite background positioning |

When to Use Flag2

• You need a cleaner, simpler HTML structure
• Flag size doesn't need to change (always 22×14 pixels)
• You're optimizing for minimal DOM nodes

Warning: Do not use the height prop with Flag2. It will cause visual distortion because the component uses sprite sheet technology where a single image file contains all flags in a grid. The component displays only the relevant portion of this sprite sheet.

Flag2 Usage

import React from 'react';
import { Flag2 } from 'national-flag-icons';

const App = () => {
  return (
    <Flag2 flagCode="us" className="myFlag" style={{ margin: '5px' }} />
  );
};

export default App;

Note: Flag2 only accepts flagCode, className, and style props. The height prop is not supported.

License

MIT

Author

Attila Kiss
e-LET Kft, Hungary
GitHub: @kissato70

Contributing

Issues and pull requests are welcome! Please report bugs or request features on the GitHub Issues page.

Support the Project

If you find this component useful, please consider supporting its development:

Your support helps maintain and improve this project. Thank you! 🙏