@mitraai/country-flags

Tree-shakeable country flag SVG React components, raw SVG assets, strongly-typed country codes, emoji flags, and CDN helpers — all generated from lipis/flag-icons.

• 🇮🇳 250 countries (ISO 3166-1 alpha-2), in 4x3 and 1x1 ratios
• 🌳 Tree-shakeable — importing one flag ships ~0.8 KB, not the whole set
• ⚛️ React components with full SVGProps support + accessible title
• 📦 Dual ESM + CJS builds with complete TypeScript declarations
• 🔤 Strongly-typed CountryCode union and metadata
• 🌐 CDN-ready URL helpers for SVG and PNG assets
• ⏭️ Works with React, Next.js (App + Pages Router), Vite, and plain JS
• 🖥️ SSR/RSC-safe — components are pure and stateless

Everything is generated from SVGs. The package ships SVG + React only; PNGs are served by the companion CDN. See FLAG ASSET STRATEGY.

Installation

npm install @mitraai/country-flags
# react is an optional peer dependency (only needed for the components)
npm install react react-dom

Usage

React components (tree-shakeable)

import { IN, US, FR } from '@mitraai/country-flags/react/4x3';
import { IN as INSquare } from '@mitraai/country-flags/react/1x1';

export function Example() {
  return (
    <>
      <IN width={30} />
      <US height={20} />
      <FR className="flag" title="Flag of France" />
      <INSquare width={24} />
    </>
  );
}

Every component accepts all native SVG props plus an optional title:

interface FlagProps extends React.SVGProps<SVGSVGElement> {
  title?: string;
}

Helper functions

import {
  getFlagSvgUrl,
  getFlagPngUrl,
  setFlagBaseUrl,
  isValidCountryCode,
  getAllCountryCodes,
  getCountryName,
  getCountryEmoji,
  searchCountries,
} from '@mitraai/country-flags';

getCountryName('IN');            // 'India'
getCountryEmoji('IN');           // '🇮🇳'
isValidCountryCode('XX');        // false
getAllCountryCodes();            // ['AD', 'AE', ... , 'ZW']
getFlagSvgUrl('IN');             // '/svg/in.svg'
getFlagPngUrl('IN', 48);         // '/png/48x36/in.png'
searchCountries('ind');          // [{ code: 'IN', name: 'India', ... }, ...]

getFlagComponent lives on the ratio subpaths (it is a React concern):

import { getFlagComponent } from '@mitraai/country-flags/react/4x3';
const Flag = getFlagComponent('IN'); // React component or undefined

CDN support

Point the URL helpers at your CDN once, at startup:

import { setFlagBaseUrl, getFlagSvgUrl, getFlagPngUrl } from '@mitraai/country-flags';

setFlagBaseUrl('https://flags.company.com');

getFlagSvgUrl('IN');       // https://flags.company.com/svg/in.svg
getFlagPngUrl('IN', 48);   // https://flags.company.com/png/48x36/in.png
getFlagPngUrl('IN', 160);  // https://flags.company.com/png/160x120/in.png

Available PNG widths: 16, 20, 24, 28, 32, 36, 40, 48, 56, 60, 64, 80, 160, 256 (heights follow the 4:3 ratio). See docs/CDN.md.

Metadata

import { COUNTRIES, getCountryMetadata } from '@mitraai/country-flags';

getCountryMetadata('IN');
// { code: 'IN', name: 'India', emoji: '🇮🇳', svg: '/svg/in.svg', png: '/png/48x36/in.png' }

Raw SVG import

// Resolved by the "./svg/*" export (bundler/CDN dependent)
import inFlag from '@mitraai/country-flags/svg/in.svg';

Exports map

| Subpath | Contents | | --- | --- | | . | Helpers, metadata, constants, and types (framework-agnostic) | | ./react/4x3 | 4:3 flag components + getFlagComponent | | ./react/1x1 | 1:1 flag components + getFlagComponent | | ./helpers | URL/metadata helpers only | | ./metadata | COUNTRIES, COUNTRY_CODES, … | | ./svg/* | Raw optimized SVG files |

The root entry is intentionally React-free so URL/metadata helpers work in any runtime. Import components from the ratio subpaths.

How it works

Only SVGs are committed to Git; everything else is generated:

npm run sync-flags   # download + filter + normalize upstream SVGs -> assets/svg
npm run build        # generate metadata, types, components, exports, SVGs -> bundle
npm test

npm run build runs, in order: generate:metadata → generate:react → generate:exports → generate:svg, then bundles with tsup. See docs/CONTRIBUTING.md and docs/FLAG-SYNC.md.

API reference

Full API in docs/API.md.

License

MIT © mitraAI. Flag artwork from lipis/flag-icons (MIT). See LICENSE.