# national-flag-icons

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

Latest version **2.0.0** (published 2025-11-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install national-flag-icons
pnpm add national-flag-icons
yarn add national-flag-icons
bun add national-flag-icons
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2025-11-29 |
| First published | 2021-05-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 413.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | kissato70 |
| Maintainers | kissato70 |
| Keywords | react, typescript, flag, country, icon, language |

## Links

- npm: https://www.npmjs.com/package/national-flag-icons
- Repository: https://github.com/kissato70/national-flag-icons
- Homepage: https://github.com/kissato70/national-flag-icons#readme
- Issues: https://github.com/kissato70/national-flag-icons/issues
- Funding: http://bit.ly/kissato70_paypal_donate
- npm.io page: https://npm.io/package/national-flag-icons

## Alternatives

- [@fortawesome/react-fontawesome](https://npm.io/package/@fortawesome/react-fontawesome.md) — 2.2M weekly downloads
- [roboto-fontface](https://npm.io/package/roboto-fontface.md) — 196.0K weekly downloads
- [@react-native-vector-icons/common](https://npm.io/package/@react-native-vector-icons/common.md) — 150.4K weekly downloads
- [@procore/core-icons](https://npm.io/package/@procore/core-icons.md) — 4.6K weekly downloads
- [@react-md/material-icons](https://npm.io/package/@react-md/material-icons.md) — 1.6K weekly downloads

## Recent versions

- 2.0.0 (latest) — 2025-11-29
- 1.0.1 — 2021-05-16
- 1.0.0 — 2021-05-08

## README

# 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

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

## Usage

### Basic Usage (JavaScript)
```javascript
import React from 'react';
import Flag from 'national-flag-icons';

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

export default App;
```

### TypeScript Usage
```typescript
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.

<br>  

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

```javascript
<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

```typescript
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>
);
```


<br>

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

```javascript
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.
<br><br>

## License

MIT

## Author

**Attila Kiss**  
[e-LET Kft](https://e-let.hu), Hungary  
GitHub: [@kissato70](https://github.com/kissato70)

## Contributing

Issues and pull requests are welcome! Please report bugs or request features on the [GitHub Issues page](https://github.com/kissato70/national-flag-icons/issues).

## Support the Project

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

[![Donate](https://img.shields.io/badge/Donate-PayPal-blue.svg)](https://bit.ly/kissato70_paypal_donate)

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

---
_Source: https://npm.io/package/national-flag-icons · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._