Skip to content
country-kit

API

Import country-kit/flags only if you need inline SVG. 

import { getCountry, getFlagSvgUrl, searchCountries } from 'country-kit';
import { getFlagSvg } from 'country-kit/flags';

const japan = getCountry('JP');
getFlagSvgUrl('JP');     // CDN SVG
getFlagSvg('JP');        // inline SVG markup
searchCountries('uk');   // United Kingdom
searchCountries('.uk');  // same, via IANA TLD

Lookup

getCountry(id) Alpha-2, alpha-3, or numeric (`US`, `USA`, `840`).
getCountryByCode(code) ISO 3166-1 alpha-2 only.
getCountryByAlpha3(alpha3) ISO 3166-1 alpha-3.
getCountryByNumeric(numeric) UN M49 / ISO numeric; `"84"` pads to `"084"`.
getCountryByTld(tld) IANA ccTLD. `".uk"` and `"uk"` both resolve to GB.
getCountryName(code) ISO English short name.
getCountryCommonName(code) Common name (`United States`).
getAlpha3Code / getNumericCode Code conversions from alpha-2.
getCallingCode(code) ITU-T E.164 country code (`AI` → `+1`).
getDialCode(code) Phone-input prefix (`AI` → `+1264`).
getCountryTld / Capital / Currencies IANA TLD, capital, ISO 4217 codes.
getCountryFlag(code) Unicode regional-indicator emoji.
getFlagSvgUrl(code, options?) CDN SVG URL (`4x3` or `1x1`).

Lists and search

getAllCountries(options?) Filter by region, subregion, independent; sort by name/code/dial.
getIndependentCountries() ISO independent = yes (195).
getCountrySelectOptions() `{ value, label, dialCode, flag, flagSvgUrl }` for a select.
searchCountries(query, options?) Names, aliases, codes, TLDs, currencies, capitals.
getCountriesByCallingCode(code) E.164 match; `+1264` resolves NANP NPAs.
getCountriesByCurrency(code) ISO 4217 alphabetic code (`EUR`, `usd`).
getCountriesByRegion / Subregion UN M49 grouping.
listRegions / listSubregions / listCurrencies Distinct region names and currency codes.

Validation

isValidCountryCode(code) Type guard for assigned alpha-2 codes.
isValidCallingCode(code) E.164 format: `+` and 1–3 digits.

Select options

import { getCountrySelectOptions } from 'country-kit';

const options = getCountrySelectOptions({ independent: true });
// { value: 'FR', label: '🇫🇷 France', dialCode: '+33',
//   flag: '🇫🇷', flagSvgUrl: 'https://…/fr.svg' }

Calling code vs dial prefix

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

getCallingCode('AI'); // '+1'     ITU-T E.164
getDialCode('AI');    // '+1264'  +1 and Anguilla NPA

// US and Canada stay +1 (no single NPA)

Country

interface Country {
  code: CountryCode;          // 'AD' | 'AE' | … 249 assigned
  name: string;               // ISO English short name
  commonName: string;
  alpha3: string;
  numeric: string;            // UN M49, 3 digits
  callingCode: string;        // ITU-T E.164
  callingCodes: readonly string[];
  dialCode: string;
  region: string | null;
  subregion: string | null;
  independent: boolean;
  tld: string | null;         // '.uk' for GB
  capital: string | null;
  currencies: readonly string[];
  flag: string;               // emoji
  nanpAreaCodes?: readonly string[];
}

Breaking changes in 2.0