country-kit
A comprehensive TypeScript library providing accurate ISO 3166-1 country data, including country codes, names, calling codes, and Unicode flag emojis.
Why country-kit?
country-kit is designed to be the go-to solution for handling country-related data in modern JavaScript/TypeScript applications. It provides:
- 🎯 Accuracy: Complete ISO 3166-1 compliant country data
- 🔒 Type Safety: Full TypeScript support with precise types
- 🪶 Lightweight: Zero dependencies, tree-shakeable
- 🚀 Performance: Optimized for both browser and Node.js
- 🌍 Comprehensive: Includes names, codes, calling codes, and flags
Features
- 📚 Complete ISO 3166-1 Coverage: Full support for alpha-2, alpha-3 codes, and country names
- 🎯 Strict Validation: Robust input validation and error handling
- 🔒 Type Safety: Comprehensive TypeScript types and interfaces
- 🪶 Tree-Shakeable: Import only what you need
- ⚡ Optimized: Fast lookups and efficient data structures
- 🌐 Unicode Flags: Correct flag emoji handling
- 📞 Calling Codes: Accurate international dialing codes
Installation
# npm
npm install country-kit
# yarn
yarn add country-kit
# pnpm
pnpm add country-kit
Quick Start
import { getCountryByCode, searchCountries } from 'country-kit';
// Get country details
const us = getCountryByCode('US');
console.log(us);
// {
// code: 'US',
// name: 'United States of America',
// alpha3: 'USA',
// callingCode: '+1',
// flag: '🇺🇸'
// }
// Search countries
const results = searchCountries('united', { limit: 2 });
console.log(results);
// Returns matching countries like United States, United Kingdom
API Reference
Functions
getCountryName(code: CountryCode): string | undefined
Returns the country name for a given ISO 3166-1 alpha-2 country code.
getCountryByCode(code: CountryCode): Country | undefined
Returns complete country information including name, alpha-3 code, calling code, and flag.
getCallingCode(code: CountryCode): string | undefined
Returns the international calling code (with + prefix) for a given country code.
getAlpha3Code(code: CountryCode): string | undefined
Returns the ISO 3166-1 alpha-3 code for a given alpha-2 country code.
getCountryFlag(code: CountryCode): string | undefined
Returns the flag emoji for a given country code.
getAllCountries(): Country[]
Returns an array of all countries with their complete information.
searchCountries(query: string, options?: CountrySearchOptions): Country[]
Searches for countries by name or code using case-insensitive matching.
Options:
limit?: number - Maximum number of results to returnexact?: boolean - Whether to match exactly (default: false)includeCodes?: boolean - Whether to search by country codes (alpha-2, alpha-3) as well (default: true)
isValidCountryCode(code: string): boolean
Validates if a string is a valid ISO 3166-1 alpha-2 country code.
isValidCallingCode(callingCode: string): boolean
Validates if a string matches the format of an international calling code (must start with '+' followed by 1-4 digits).
getCountriesByCallingCode(callingCode: string): Country[]
Returns an array of countries that share the specified calling code.
Types
type CountryCode = string; // ISO 3166-1 alpha-2 code
interface Country {
name: string;
code: CountryCode;
alpha3: string;
callingCode: string;
flag: string;
}
Examples
Country Selection in Forms
import { getAllCountries, isValidCountryCode } from 'country-kit';
const countries = getAllCountries();
const formattedOptions = countries.map(country => ({
value: country.code,
label: `${country.flag} ${country.name} (${country.callingCode})`
}));
Phone Number Formatting
import { getCallingCode, isValidCallingCode } from 'country-kit';
function formatPhoneNumber(countryCode: string, number: string) {
const callingCode = getCallingCode(countryCode);
return callingCode ? `${callingCode} ${number}` : number;
}
Contributing
We welcome contributions to country-kit! Here's how you can help:
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature)
- Commit your changes (
git commit -m 'Add some amazing feature')
- Push to the branch (
git push origin feature/amazing-feature)
- Open a Pull Request
Please make sure to:
- Update the documentation
- Add/update tests as needed
- Follow the existing code style
- Run the test suite before submitting
License
This project is licensed under the ISC License - see the LICENSE file for details.
Made with ❤️ by Vipin Mishra
