Data about countries - like their ISO codes and currencies
npm install country-data-listbash
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`)