countries-list

What is countries-list?

The countries-list npm package provides a comprehensive list of countries, their codes, and other related information. It is useful for applications that need to display or process country-related data.

What are countries-list's main functionalities?

Get list of all countries

This feature allows you to retrieve a list of all countries along with their details such as name, native name, phone code, continent, capital, currency, and languages.

const { countries } = require('countries-list');
console.log(countries);

Get list of all continents

This feature allows you to retrieve a list of all continents and their corresponding codes.

const { continents } = require('countries-list');
console.log(continents);

Get list of all languages

This feature allows you to retrieve a list of all languages and their corresponding codes.

const { languages } = require('countries-list');
console.log(languages);

Get list of all currencies

This feature allows you to retrieve a list of all currencies and their corresponding codes.

const { currencies } = require('countries-list');
console.log(currencies);

Other packages similar to countries-list

country-list

The country-list package provides a list of countries and their ISO 3166-1 alpha-2 codes. It is simpler compared to countries-list and focuses mainly on country names and codes.

i18n-iso-countries

The i18n-iso-countries package provides ISO 3166-1 country codes with translations for country names in multiple languages. It is more focused on internationalization and localization compared to countries-list.

world-countries

The world-countries package provides detailed information about countries, including names, codes, and geographical data. It is similar to countries-list but includes more detailed geographical information.

README

Countries, Languages & Continents data

Continents & countries: ISO 3166-1 alpha-2 code (with alpha-2 to alpha-3 set), name, ISO 639-1 languages, capital and ISO 4217 currency codes, native name, calling codes. Lists are available in JSON, CSV and SQL formats. Also, contains separate JSON files with additional country Emoji flags data.

Version 3.0: Breaking changes

Version 3 comes with some data structure changes. It was completely reworked under the hood with TypeScript, ESM exports and Turborepo file structure.

Everything is strongly typed so you can easily use data with auto-complete in your IDE.

Note: If your projects depend on the old structure, carefully specify required versions in your dependencies.

Installation

Package is available via:

• NPM npm install countries-list
• Composer / Packagist composer require annexare/countries-list

Usage (version 3.x)

Module exports continents, countries, languages and utility functions.

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

// Main data and utils
import { continents, countries, languages } from 'countries-list'
// Utils
import { getCountryCode, getCountryData, getCountryDataList, getEmojiFlag } from 'countries-list'

// Minimal data in JSON
import countries2to3 from 'countries-list/minimal/countries.2to3.min.json'
import countries3to2 from 'countries-list/minimal/countries.3to2.min.json'
import languageNames from 'countries-list/minimal/languages.native.min'

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

Built files are in the dist directory of this repository, and packages/countries directory contains source data.

Note: JS build contains ES modules, CommonJS and IIFE (for now)

• CJS cjs/index.js
• ESM mjs/index.js
• IIFE index.iife.js

Data structure examples

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,
  },
  // ...
}

Contributing to this repository

Everything is generated from strongly typed files in packages/countries/src, including SQL file.

Everything in dist is generated, so please make data related changes ONLY to files from packages/countries, commit them. Use npm run build (or turbo build, turbo test) command to build/test generated files.

Credits

Prepared by Annexare Studio from different public sources. Feel free to use it as you need in your apps or send updates into this public repository. It's under MIT license.