country-kit

ISO 3166-1 country data for TypeScript: codes, names, ITU-T E.164 calling codes, UN M49 regions, IANA ccTLDs, ISO 4217 currencies, Unicode flag emoji, and Wikipedia SVG flags.

• ISO 3166-1 assigned codes and English short names, UN M49, ITU-T E.164, IANA ccTLDs, ISO 4217
• CountryCode is a union of all 249 assigned alpha-2 codes
• Zero runtime dependencies
• Common names, search aliases, NANP area codes, Unicode flags, Wikipedia SVG flags

Docs: getting started, playground, examples, API, changelog.

Install

npm install country-kit

pnpm add country-kit

bun add country-kit

Requires Node 18 or newer. ESM and CommonJS. The package sets sideEffects: false.

Quick start

import { getCountry, searchCountries } from 'country-kit';

const us = getCountry('US');
// {
//   code: 'US',
//   name: 'United States of America',  // ISO short name
//   commonName: 'United States',
//   alpha3: 'USA',
//   numeric: '840',
//   callingCode: '+1',                 // ITU-T E.164
//   dialCode: '+1',
//   region: 'Americas',
//   tld: '.us',
//   currencies: ['USD'],
//   flag: '🇺🇸'
// }

searchCountries('uk');        // United Kingdom (alias)
searchCountries('Vietnam');   // Viet Nam
searchCountries('.uk');       // United Kingdom (IANA TLD)
searchCountries('TRY');       // Türkiye (ISO 4217)

There is no React or Vue package. Import these functions from any JS runtime.

Data sources

| Field | Standard | Notes | | --- | --- | --- | | code, alpha3, name | ISO 3166-1 | All 249 officially assigned codes. name is the ISO English short name. | | numeric, region, subregion | UN M49 | Numeric codes are identical to ISO 3166-1 numeric. Antarctica and Taiwan have no UN region. | | callingCode | ITU-T E.164 | Country calling codes only (1-3 digits). NANP members are +1. Area codes live on nanpAreaCodes. | | nanpAreaCodes | NANP | Area codes for territories that share +1. | | independent | ISO 3166 | Independent-territory flag (195 yes). | | tld | IANA | Country-code TLD. GB is .uk, not .gb. | | currencies | ISO 4217 | Alphabetic currency codes. Empty when none is assigned (Antarctica, Palestine). | | capital | Conventional English | Not an ISO field; kept for UI labels. | | flag | Unicode UTS #51 | Derived from the alpha-2 code via regional indicator symbols. | | SVG flags | Wikimedia / flag-icons | Wikipedia SVG drawings, MIT, pinned to flag-icons 7.5.0. |

Kosovo (XK) is omitted. It is a user-assigned code, not an ISO 3166-1 assigned code.

Regenerate the dataset with pnpm generate after updating files in scripts/sources/. Rebuild inline SVGs with pnpm generate:flags.

Upgrading from 1.x

Phone UIs that used getCallingCode as a dial prefix for NANP territories need getDialCode. isValidCallingCode no longer accepts a concatenated NPA such as +1264. Invalid lookups return undefined and do not call console.error.

getCallingCode('AI');        // '+1'
getDialCode('AI');           // '+1264'
isValidCallingCode('+1264'); // false
isValidCallingCode('+1');    // true

2.0 adds commonName, numeric, callingCodes, dialCode, region, subregion, independent, tld, capital, and currencies. Existing 1.x fields remain. Version notes: CHANGELOG.md.

API

Lookup

| Function | Description | | --- | --- | | getCountry(id) | Alpha-2, alpha-3, or numeric code | | getCountryByCode(code) | ISO 3166-1 alpha-2 | | getCountryByAlpha3(alpha3) | ISO 3166-1 alpha-3 | | getCountryByNumeric(numeric) | ISO 3166-1 numeric / UN M49 ("840" or "84") | | getCountryByTld(tld) | IANA ccTLD (".uk" or "uk" → GB) | | getCountryName(code) | ISO English short name | | getCountryCommonName(code) | Common English name | | getAlpha3Code(code) | Alpha-3 | | getNumericCode(code) | Numeric, zero-padded | | getCallingCode(code) | E.164 country calling code (+1 for all NANP) | | getDialCode(code) | Phone-input prefix (+1264 for Anguilla, +1 for the US) | | getCountryFlag(code) | Flag emoji, or undefined if the code is not assigned | | getFlag(code) | Flag emoji from letters (does not check that the code is assigned) | | getFlagSvgUrl(code, options?) | CDN URL (ratio: 4x3 | 1x1, source: flag-icons | flagcdn) | | getCountryTld / getCountryCapital / getCountryCurrencies | IANA TLD, capital, ISO 4217 | | getAllCountries(options?) | Optional region, subregion, independent, sortBy | | getIndependentCountries() | ISO independent = yes (195) | | getCountrySelectOptions() | { value, label, dialCode, flag, flagSvgUrl } for a select |

Search and grouping

| Function | Description | | --- | --- | | searchCountries(query, options?) | Ranked search over official names, common names, aliases, codes, TLDs, currencies, and capitals | | getCountriesByCallingCode(code) | E.164 match; +1264 also resolves NANP NPAs | | getCountriesByCurrency(code) | ISO 4217 alphabetic code (EUR, usd) | | getCountriesByRegion() / getCountriesByRegion('Europe') | UN M49 region | | getCountriesBySubregion(subregion) | UN M49 sub-region | | listRegions() / listSubregions() / listCurrencies() | Distinct names / codes |

Search options: limit, exact, includeCodes (default true).

Validation

isValidCountryCode('US');    // true  (type guard for CountryCode)
isValidCallingCode('+44');   // true  (E.164: + and 1-3 digits)
isValidCallingCode('+1264'); // false (that is +1 plus a NANP area code)

Data maps

| Export | Description | | --- | --- | | COUNTRY_CODES | Tuple of all 249 assigned alpha-2 codes | | countryCodes | Same list as readonly string[] | | countryNames | ISO English short names, same order | | countryData | Record keyed by alpha-2, including aliases | | countries | { [code]: name } map. Deprecated; use getCountryName / getAllCountries | | FLAG_ICONS_VERSION | Pinned flag-icons version (7.5.0) |

Types

type CountryCode = 'AD' | 'AE' | /* … 249 assigned alpha-2 codes … */;

interface Country {
  code: CountryCode;
  name: string;            // ISO 3166-1 English short name
  commonName: string;
  alpha3: string;
  numeric: string;
  callingCode: string;     // ITU-T E.164
  callingCodes: readonly string[];
  dialCode: string;
  region: string | null;
  subregion: string | null;
  independent: boolean;
  tld: string | null;
  capital: string | null;
  currencies: readonly string[];
  flag: string;
  nanpAreaCodes?: readonly string[];
}

Also exported: CountryData, CountryRecord, CountryListOptions, CountrySearchOptions, CountrySelectOption, CountryRegion, FlagUrlOptions, FlagRatio, FlagSource.

Examples

React and Vue previews: examples.

Country select

Store the alpha-2 code. Display commonName. independent: true excludes territories.

import { useMemo, useState } from 'react';
import { getCountry, getCountrySelectOptions } from 'country-kit';

export function ResidenceSelect() {
  const options = useMemo(
    () => getCountrySelectOptions({ independent: true }),
    [],
  );
  const [code, setCode] = useState('FR');
  const country = getCountry(code);

  return (
    <select value={code} onChange={(e) => setCode(e.target.value)}>
      {options.map((o) => (
        <option key={o.value} value={o.value}>{o.label}</option>
      ))}
    </select>
  );
}

<script setup lang="ts">
import { computed, ref } from 'vue';
import { getCountry, getCountrySelectOptions } from 'country-kit';

const options = getCountrySelectOptions({ independent: true });
const code = ref('FR');
const country = computed(() => getCountry(code.value));
</script>

<template>
  <select v-model="code">
    <option v-for="o in options" :key="o.value" :value="o.value">
      {{ o.label }}
    </option>
  </select>
</template>

Phone prefix

dialCode is what a phone picker should show. callingCode is the ITU-T E.164 country code.

import {
  getCallingCode,
  getCountriesByCallingCode,
  getDialCode,
  searchCountries,
} from 'country-kit';

const [match] = searchCountries('Anguilla', { limit: 1 });
getDialCode(match.code);    // '+1264'  prefix in the UI
getCallingCode(match.code); // '+1'     store as E.164 country code

getCountriesByCallingCode('+1264'); // [Anguilla]
getCountriesByCallingCode('+1');    // US, CA, AI, …

Search

import { searchCountries } from 'country-kit';

const results = searchCountries(query, { limit: 6 });
// 'uk' / '.uk' → United Kingdom
// 'Vietnam'    → Viet Nam
// 'TRY'        → Türkiye
// 'Paris'      → France

order.shipTo = results[0].code;
order.shipToLabel = results[0].commonName;

Flags

import { getCountryFlag, getFlagSvgUrl } from 'country-kit';

<img src={getFlagSvgUrl('JP')} alt="Japan" />
<img src={getFlagSvgUrl('JP', { ratio: '1x1' })} alt="" />
getCountryFlag('JP'); // '🇯🇵'

<script setup lang="ts">
import { getCountryFlag, getFlagSvgUrl } from 'country-kit';
</script>

<template>
  <img :src="getFlagSvgUrl('JP')" alt="Japan" />
  <img :src="getFlagSvgUrl('JP', { ratio: '1x1' })" alt="" />
</template>

getFlagSvgUrl(code, { source: 'flagcdn' }) uses the Flagpedia CDN (1x1 is PNG). Default source is flag-icons on jsDelivr.

Offline inline markup (larger entry): import { getFlagSvg } from 'country-kit/flags'.

TLD lookup

import { getCountryByTld } from 'country-kit';

function countryFromHost(value: string) {
  const host = value.includes('@')
    ? value.split('@').pop()!
    : value.replace(/^https?:\/\//, '').split(/[/?#]/)[0];
  return getCountryByTld('.' + host.split('.').pop());
}

countryFromHost('https://www.gov.uk'); // United Kingdom (GB, not .gb)
countryFromHost('[email protected]');        // Germany
countryFromHost('https://npmjs.com');  // undefined (.com is not a ccTLD)

Currency

import { getCountriesByCurrency, listCurrencies } from 'country-kit';

listCurrencies(); // ['AED', 'AFN', …]
const euro = getCountriesByCurrency('EUR');
pricing.enabledMarkets = euro.map((c) => c.code);

Regions

import { getAllCountries, getIndependentCountries, listRegions } from 'country-kit';

listRegions(); // Africa, Americas, Asia, Europe, Oceania

const europe = getAllCountries({
  region: 'Europe',
  independent: true,
  sortBy: 'commonName',
});

getIndependentCountries(); // 195 sovereign states

Validation

import {
  getCountry,
  isValidCallingCode,
  isValidCountryCode,
  type CountryCode,
} from 'country-kit';

function parseCountry(raw: string): CountryCode | undefined {
  if (isValidCountryCode(raw)) return raw;
  return getCountry(raw)?.code; // 'USA' / '840' → 'US'
}

parseCountry('GB');            // 'GB'
parseCountry('XK');            // undefined (not ISO assigned)
isValidCallingCode('+44');     // true
isValidCallingCode('+1264');   // false (NANP area code, not E.164)

Package layout

src/
  index.ts              public exports (does not include inline SVGs)
  api.ts                lookup, search, validation
  data.ts               indexes (Maps / Sets) over the dataset
  flags.ts              Unicode regional-indicator flags
  flag-urls.ts          version-pinned CDN URLs
  svg-flags.ts          country-kit/flags entry (inline SVG)
  types.ts
  country-code.ts       generated CountryCode union
  data/countries.json   generated from scripts/sources
  data/flag-svgs.json   generated Wikipedia SVGs (optional entry)
scripts/
  generate-data.mjs
  generate-flags.mjs
  sources/              ISO 3166-1 / UN M49 / extras / flag-icons license

Import country-kit/flags only for inline SVG. The core package is the JSON dataset plus lookups.

License

ISC. See LICENSE.

SVG flags are MIT (flag-icons / Wikipedia). See scripts/sources/flag-icons.LICENSE.