A modern TypeScript library for managing and retrieving comprehensive country data with a simple and intuitive API.
- 🌍 Comprehensive Data Extensive country info including names, codes, currencies, languages, and more
- 🔍 Smart Search Powerful filtering and search capabilities
- 🌐 i18n Ready Support for multiple languages and translations
- 💪 Type-Safe Full TypeScript support with comprehensive type definitions
- 🎯 ISO Compliant Implements ISO 3166-1 standards for country codes
- 🧪 Well-Tested Comprehensive test suite ensuring reliability
- 📦 Zero Dependencies Lightweight and self-contained
- 🔄 Caching Built-in caching system for optimal performance
# Using npm
npm install ts-countries
# Using yarn
yarn add ts-countries
# Using pnpm
pnpm add ts-countries
# Using bun
bun add ts-countriesimport { countries, country } from 'ts-countries'
// Get a single country
const usa = country('US')
console.log(usa.getName()) // Returns 'United States'
console.log(usa.getIsoAlpha2()) // Returns 'US'
console.log(usa.getIsoAlpha3()) // Returns 'USA'
// Get all countries
const allCountries = countries()
// Get detailed country list
const detailedCountries = countries(true) // longlist format
// Get hydrated Country instances
const countryInstances = countries(false, true) // returns Country[]import { Country, CountryLoader } from 'ts-countries'
// Working with country data
const usa = country('US')
// Access various country properties
console.log(usa.getCapital()) // Get capital city
console.log(usa.getCurrencies()) // Get currency information
console.log(usa.getLanguages()) // Get official languages
console.log(usa.getTimezones()) // Get timezone information
console.log(usa.getGeodata()) // Get geographic data
// Get translations
console.log(usa.getTranslations()) // Get all translations
console.log(usa.getTranslation('fra')) // Get French translation
// Working with native names
console.log(usa.getNativeName()) // Get native name
console.log(usa.getNativeNames()) // Get all native names
// Geographic information
console.log(usa.getRegion()) // Get region
console.log(usa.getSubregion()) // Get subregion
console.log(usa.getContinent()) // Get continent
console.log(usa.getBorders()) // Get bordering countries
// Additional metadata
console.log(usa.getDemonym()) // Get demonym
console.log(usa.getCallingCode()) // Get calling code
console.log(usa.getTld()) // Get top-level domainimport { CountryCollection } from 'ts-countries'
const collection = new CountryCollection(countries(false, true))
// Filter by region
const europeanCountries = collection.where('geo.region', 'Europe')
// Filter by currency
const euroCountries = collection.where('currency.EUR')
// Filter using comparison operators
const largeCountries = collection.where('geo.area', '>', 1000000)
// Complex filtering
const northAmericanEnglishSpeaking = collection
.where('geo.subregion', 'North America')
.where('languages.eng', 'English')Represents a single country with comprehensive data and helper methods.
Static class for loading country data with built-in caching.
Collection class for working with multiple countries and filtering.
getName(): Get country namegetOfficialName(): Get official country namegetNativeName(languageCode?): Get native namegetIsoAlpha2(): Get ISO 3166-1 alpha-2 codegetIsoAlpha3(): Get ISO 3166-1 alpha-3 codegetIsoNumeric(): Get ISO 3166-1 numeric codegetCurrencies(): Get currency informationgetLanguages(): Get official languages- And many more...
country(code: string, hydrate?: boolean): Load single countrycountries(longlist?: boolean, hydrate?: boolean): Load all countrieswhere(key: string, operator: string, value?: any): Filter countries
The library throws descriptive exceptions for various error conditions:
- Invalid Country Code: When a country code doesn't exist
- Missing Data: When required country data is missing
- Invalid Format: When data format is incorrect
Please see CONTRIBUTING for details.
For help, discussion about best practices, or any other conversation that would benefit from being searchable:
For casual chit-chat with others using this package:
Join the Stacks Discord Server
“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.
Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎
- Rinvex for the original PHP library
- Chris Breuer for the TypeScript conversion
We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.
The MIT License (MIT). Please see LICENSE for more information.
Made with 💙
