Country Data List

A comprehensive library providing access to standardized country, currency, and language information.


This is a fork of https://github.com/OpenBookPrices/country-data.

Features

- Comprehensive Data: Access to country names, ISO codes, currencies, languages, timezones, and more
- Multiple Formats: ES modules and UMD formats supported for browser and Node.js
- Type Definitions: Full TypeScript support with type definitions
- Tree-Shaking Support: Import only what you need to keep bundle size small
- Zero Dependencies: Lightweight and self-contained
- Timezone Support: IANA timezone data for all countries
- Flexible Search: String-based and object-based lookup functionality

Installation

``bash
npm install country-data-list

or

yarn add country-data-list
`

Usage

$3

`javascript
import { countries, currencies, languages, timezones, lookup } from 'country-data-list';

// Get all countries
console.log(countries.all);

// Get a specific country by alpha2 code
console.log(countries['US']);

// Get a specific currency
console.log(currencies['USD']);

// Get timezones for a country
console.log(timezones.getTimezonesByCountry('US'));

// Get all timezones
console.log(timezones.all);

// Search for countries (string-based search)
const results = lookup.countries('united');
console.log(results);

// Search for countries (object-based search)
const exactResults = lookup.countries({ name: 'United States' });
console.log(exactResults);
`

$3

`html

`

$3

`javascript
const { countries, currencies, languages } = require('country-data-list');

// Get all countries
console.log(countries.all);
`

$3

Tree-shaking allows you to import only the specific parts you need, resulting in smaller bundle sizes. The library offers multiple ways to optimize your imports:

#### Method 1: Selective Named Imports

`javascript
// Import only the parts you need
import { countries, timezones } from 'country-data-list';
import { currencies } from 'country-data-list';
import { languages } from 'country-data-list';

// Or import specific utility functions
import { getSymbolFromCurrency, getUtcOffset } from 'country-data-list';
`

#### Method 2: Direct Data Module Imports

For even smaller bundles, import the data modules directly:

`javascript
// Most efficient imports for minimal bundle size
import countries from 'country-data-list/data/countries';
import currencies from 'country-data-list/data/currencies';
import languages from 'country-data-list/data/languages';
import timezones from 'country-data-list/data/timezones';
import regions from 'country-data-list/data/regions';
import continents from 'country-data-list/data/continents';
import { getSymbolFromCurrency } from 'country-data-list/data/currency-symbol';
`

#### Method 3: Individual Currency Symbol Functions

For applications that only need currency symbols, you can import just the functions you need:

`javascript
// Import only the currency symbol function (smallest bundle size)
import { getSymbolFromCurrency } from 'country-data-list/data/currency-symbol';

// Or import specific functions as needed
import {
getSymbolFromCurrency,
getNameFromCurrency
} from 'country-data-list/data/currency-symbol';

// Usage
console.log(getSymbolFromCurrency('USD')); // $
console.log(getNameFromCurrency('USD')); // US Dollar
`

#### Bundle Size Comparison

| Import Method | Approximate Bundle Size | Data Included |
|---------------|------------------------|---------------|
| import * from 'country-data-list' | ~500KB | All data and functions |
| import { countries } from 'country-data-list' | ~200KB | Just countries data |
| import countries from 'country-data-list/data/countries' | ~150KB | Only countries data module |
| import { getSymbolFromCurrency } from 'country-data-list' | ~50KB | Just symbol function and map |
| import { getSymbolFromCurrency } from 'country-data-list/data/currency-symbol' | ~15KB | Only the specific function |

The library is designed to be fully tree-shakeable in bundlers that support ES modules like Webpack, Rollup, and esbuild.

#### Verifying Tree-Shaking

You can verify that tree-shaking works by running our test script:

`bash

Run the tree-shaking test

npm run tree-shaking-test

Compare the output file size with the full bundle

ls -la dist/tree-shaking-example.js dist/country-data-list.esm.js
`

To analyze your own project's tree-shaking:

`bash

Using Rollup with visualizer

npx rollup your-file.js -f esm -o bundle.js -p rollup-plugin-visualizer

Using webpack-bundle-analyzer with webpack

`

For more examples, check out the examples/tree-shaking.js file in the repository.

Available Data

$3

The data provided for each country includes:

- name: The English name for the country
- alpha2: The ISO 3166-1 alpha 2 code
- alpha3: The ISO 3166-1 alpha 3 code
- status: The ISO status of the entry
- currencies: An array of ISO 4217 currency codes
- languages: An array of ISO 639-2 language codes
- countryCallingCodes: International call prefixes
- ioc: The International Olympic Committee country code
- emoji: The country's flag emoji

$3

Information about currencies includes:

- code: The ISO 4217 currency code
- name: The currency name
- number: The ISO 4217 currency number
- decimals: The number of decimal digits typically used with this currency
- symbol: The currency symbol (where available)

#### Currency Symbol Utilities

The library provides several utility functions for working with currency symbols:

`javascript
import {
getSymbolFromCurrency,
getNameFromCurrency,
getSafeSymbolFromCurrency,
getSafeNameFromCurrency,
currencySymbolMap
} from 'country-data-list';

// Get currency symbol
console.log(getSymbolFromCurrency('USD')); // $
console.log(getSymbolFromCurrency('EUR')); // €
console.log(getSymbolFromCurrency('GBP')); // £

// Get currency name
console.log(getNameFromCurrency('USD')); // US Dollar

// Safe versions return the currency code if symbol/name not found
console.log(getSafeSymbolFromCurrency('UNKNOWN')); // UNKNOWN
console.log(getSafeNameFromCurrency('UNKNOWN')); // UNKNOWN

// Access the complete currency symbol map
console.log(currencySymbolMap);
`

$3

Language information includes:

- name: The language name in English
- alpha2: The ISO 639-1 code (2 character) where available
- alpha3: The ISO 639-2/T code (3 character) terminology
- bibliographic: The ISO 639-2/B bibliographic code

$3

Timezone information includes:

- Complete IANA timezone database for all countries
- Functions to get timezones by country code
- Functions to find countries using specific timezones
- UTC offset calculation for any timezone

`javascript
import { timezones } from 'country-data-list';

// Get all available timezones
console.log(timezones.all);

// Get timezones for a specific country
console.log(timezones.getTimezonesByCountry('US'));
// Output: ['America/New_York', 'America/Chicago', 'America/Denver', ...]

// Find countries using a specific timezone
console.log(timezones.getCountriesForTimezone('Europe/London'));
// Output: ['GB']

// Get UTC offset for a timezone
console.log(timezones.getUtcOffset('Europe/London'));
// Output: '+0' or '+1' depending on daylight saving time
`

$3

Access to geographical regional data:

`javascript
import { regions, continents } from 'country-data-list';

// Or import specific modules for tree-shaking
import regionsData from 'country-data-list/data/regions';
import continentsData from 'country-data-list/data/continents';

// Find regions for a country
console.log(regionsData.getRegionsForCountry('US'));
// Output: ['Northern America']

// Get countries in a region
console.log(regionsData.getCountriesInRegion('Western Europe'));
// Output: ['AT', 'BE', 'FR', 'DE', ...]
`

$3

The library includes a flexible lookup tool for finding entries with both string and object queries:

`javascript
import { lookup } from 'country-data-list';

// Object-based search (exact property matching)
const exactResults = lookup.countries({ name: 'United States' });
console.log(exactResults); // Only exact name matches
`

Contribute

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)
5. Open a Pull Request

Acknowledgement

This repository is a derived work of the following project, originally forked from:

https://github.com/OpenBookPrices/country-data

We would like to thank the original authors.

License

This project is licensed under the MIT License - see the LICENSE file for details.