react-native-country-flag-icons

Tree-shakeable country flag icons for React Native with SVG support.

Only bundle the flags you actually use.

Why This Library?

| Feature | react-native-country-flag-icons | react-native-ico-flags | react-native-svg-flagkit | |---------|:------------------------------:|:----------------------:|:------------------------:| | Tree-shaking | ✅ | ❌ | ❌ | | Bundle size (3 flags) | ~3KB | ~358KB | ~64MB | | SVG (scalable) | ✅ | ✅ | ❌ (PNG) | | TypeScript | ✅ | ❌ | ❌ | | Expo compatible | ✅ | ✅ | ❌ | | Dynamic flag component | ✅ | ✅ | ✅ | | ESM + CommonJS | ✅ | ❌ | ❌ |

The Problem

Most React Native flag libraries bundle all flags regardless of how many you use:

Your app uses 5 flags → Downloads 300+ flags → Bundle bloat 📦💥

The Solution

With tree-shaking, your bundle only includes flags you actually import:

Your app uses 5 flags → Bundles only 5 flags → Minimal bundle size ✨

Features

• Tree-shakeable - Import only what you need, bundle only what you use
• Lightweight - ~1KB per flag vs 300KB+ for entire flag libraries
• SVG-based - Crisp flags at any resolution using react-native-svg
• TypeScript - Full type definitions with CountryCode type and FlagProps
• 265 flags - All countries with ISO 3166-1 alpha-2 codes + regional flags
• Expo compatible - Works with Expo (requires expo-dev-client for react-native-svg)
• Dual package - Supports both ESM and CommonJS

Installation

# npm
npm install react-native-country-flag-icons react-native-svg

# yarn
yarn add react-native-country-flag-icons react-native-svg

React Native CLI

cd ios && pod install

Expo

npx expo install react-native-svg

Note: react-native-svg requires a development build. Run npx expo run:ios or npx expo run:android after installation.

Usage

Named imports (recommended for tree-shaking)

Best for static flags where you know the country codes at build time:

import {US, KR, JP} from 'react-native-country-flag-icons'

function MyComponent() {
  return (
    <>
      <US width={32} />
      <KR width={32} />
      <JP width={32} />
    </>
  )
}

Dynamic Flag component

For dynamic country codes (e.g., from API), use the Flag component:

import {Flag} from 'react-native-country-flag-icons'

function CountryItem({countryCode}: {countryCode: string}) {
  return <Flag code={countryCode} width={32} />
}

Note: The dynamic Flag component imports all flags internally, so tree-shaking won't apply. Use named imports when possible for optimal bundle size.

Custom dimensions

import {US} from 'react-native-country-flag-icons'

// Width only (height auto-calculated with 3:2 aspect ratio)
<US width={48} />

// Both width and height
<US width={48} height={32} />

With styles

import {US} from 'react-native-country-flag-icons'

<US
  width={32}
  style={{borderRadius: 4, overflow: 'hidden'}}
/>

Props

Named Flag Components (US, KR, JP, ...)

| Prop | Type | Default | Description | |------|------|---------|-------------| | width | number | 32 | Width in pixels | | height | number | width / 1.5 | Height (auto-calculated if not provided) | | style | ViewStyle | - | Style for the SVG container | | ...props | SvgProps | - | All other props passed to SVG |

Dynamic Flag Component

| Prop | Type | Default | Description | |------|------|---------|-------------| | code | CountryCode | required | ISO 3166-1 alpha-2 country code | | width | number | 32 | Width in pixels | | height | number | width / 1.5 | Height (auto-calculated if not provided) | | style | ViewStyle | - | Style for the SVG container |

Available Flags

All 265 flags use ISO 3166-1 alpha-2 country codes:

import {
  US,  // United States
  KR,  // South Korea
  JP,  // Japan
  CN,  // China
  GB,  // United Kingdom
  FR,  // France
  DE,  // Germany
  // ... and 258 more
} from 'react-native-country-flag-icons'

Regional flags

import {
  GB_ENG,  // England
  GB_SCT,  // Scotland
  GB_WLS,  // Wales
  GB_NIR,  // Northern Ireland
  ES_CT,   // Catalonia
} from 'react-native-country-flag-icons'

TypeScript

Full TypeScript support with exported types:

import {
  US,
  Flag,
  FlagProps,
  CountryCode,
  countryCodes
} from 'react-native-country-flag-icons'

// FlagProps type for custom wrappers
const MyFlag: React.FC<FlagProps> = (props) => <US {...props} />

// CountryCode type for type-safe country codes
const code: CountryCode = 'US'

// countryCodes array for validation or iteration
if (countryCodes.includes(userInput as CountryCode)) {
  // valid country code
}

Bundle Size Comparison

| Scenario | This Library | react-native-ico-flags | react-native-svg-flagkit | |----------|-------------:|----------------------:|-------------------------:| | 1 flag | ~1KB | ~358KB | ~64MB | | 5 flags | ~5KB | ~358KB | ~64MB | | 10 flags | ~10KB | ~358KB | ~64MB | | All flags | ~300KB | ~358KB | ~64MB |

Credits

• Flag SVGs sourced from country-flag-icons
• SVG rendering powered by react-native-svg

License

MIT