2.0.0 • Published 10 months ago

national-flag-icons

Licence

MIT

Version

2.0.0

Deps

Size

414 kB

Vulns

Weekly

Summary Dependency Versions

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

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.