countries-list Documentation

The library organizes data into four main objects: continents, countries, languages, and currencies.

• Continents: Keyed by TContinentCode (e.g., AF, EU), mapping to the continent name.
• Countries: Keyed by TCountryCode (e.g., UA), containing name, native name, phone prefix, continent code, capital, currency array, and languages array.
• Languages: Keyed by TLanguageCode (e.g., uk), containing name, native name, and rtl (right-to-left) indicator.
• Currencies: Keyed by TCurrencyCode (e.g., UAH), containing name, native name, symbol, symbolNative, numeric code, and decimals count.

const continents = {
  AF: 'Africa',
  AN: 'Antarctica',
  AS: 'Asia',
  EU: 'Europe',
  NA: 'North America',
  OC: 'Oceania',
  SA: 'South America',
}

const countries = {
  UA: {
    name: 'Ukraine',
    native: 'Україна',
    phone: [380],
    continent: 'EU',
    capital: 'Kyiv',
    currency: ['UAH'],
    languages: ['uk'],
  },
}

const languages = {
  uk: {
    name: 'Ukrainian',
    native: 'Українська',
  },
  ur: {
    name: 'Urdu',
    native: 'اردو',
    rtl: 1,
  },
}

const currencies = {
  UAH: {
    name: 'Ukrainian Hryvnia',
    native: 'українська гривня',
    symbol: '₴',
    symbolNative: '₴',
    numeric: '980',
    decimals: 2,
  },
}

The countries object is a mapping where keys are ISO 3166-1 alpha-2 country codes and values are objects containing detailed country information.

Each country object typically includes:

• name: The English name of the country.
• native: The name of the country in its native language.
• phone: An array of phone country codes.
• continent: The primary continent code (e.g., 'AF', 'EU', 'AS').
• continents: (Optional) An array of continent codes if the country spans multiple continents.
• capital: The name of the capital city.
• currency: An array of ISO 4217 currency codes.
• languages: An array of ISO 639-1 language codes.
• alias: (Optional) An array of alternative names for the country.
• partOf: (Optional) The ISO code of the country it belongs to (e.g., for territories).

Note: Some entries like Antarctica (AQ) may have empty arrays for currency or languages and an empty string for capital.

Full currency data is an opt-in import via the countries-list/currencies subpath to keep the main bundle small. This includes English and native names, UI symbols, native symbols, 3-digit numeric codes, and decimal counts.

Utilities provided:

• currencies: An object containing all currency data keyed by code.
• getCurrency(code): Returns ICurrencyData for a specific code (e.g., 'JPY').
• getCurrencyByNumeric(numericCode): Performs a lookup using the 3-digit numeric code (e.g., '840' for USD).

import type { ICurrency, ICurrencyData, TCurrencyCode } from 'countries-list'
import { currencies, getCurrency, getCurrencyByNumeric } from 'countries-list/currencies'

// Minimal maps (code -> value)
import currencySymbols from 'countries-list/minimal/currencies.symbol.min.json'
import currencyNumbers from 'countries-list/minimal/currencies.numeric.min.json'

// Example usage
currencies.UAH // { name: 'Ukrainian Hryvnia', native: 'українська гривня', symbol: '₴', symbolNative: '₴', numeric: '980', decimals: 2 }
getCurrency('JPY') // ICurrencyData: { code: 'JPY', name: 'Japanese Yen', symbol: '¥', decimals: 0, ... }
getCurrencyByNumeric('840') // ICurrencyData for USD

The main module provides access to continents, countries, and languages data, along with utility functions for lookups. It supports ESM, CJS, and IIFE formats.

Key utilities include:

• getCountryCode(name): Returns the ISO 3166-1 alpha-2 code for a given country name (supports English and native names).
• getCountryData(code): Returns an ICountryData object for a specific country code.
• getCountryDataList(): Returns the full list of country data.
• getEmojiFlag(code): Returns the emoji flag for a country code.

import type {
  ICountry,
  ICountryData,
  ILanguage,
  TContinentCode,
  TCountryCode,
  TLanguageCode,
} from 'countries-list'

import { continents, countries, languages } from 'countries-list'
import { getCountryCode, getCountryData, getCountryDataList, getEmojiFlag } from 'countries-list'

// Example usage
getCountryCode('Ukraine') // 'UA'
getCountryCode('Україна') // 'UA'
getCountryData('UA') // ICountryData