Introduction

country-kit is a lightweight TypeScript library providing ISO country data and utilities for working with country codes, names, calling codes and flags.

Features

Zero dependencies
TypeScript support
ISO 3166-1 alpha-2 and alpha-3 codes
Country names and flags
International calling codes
Search and validation utilities

Installation

npm install country-kit

Usage

Basic Usage

import { getCountryByCode, searchCountries } from 'country-kit';

// Get country details
const usa = getCountryByCode('US');
// => { code: 'US', name: 'United States', alpha3: 'USA', callingCode: '+1', flag: '🇺🇸' }

// Search countries
const results = searchCountries('united');
// => [{ code: 'US', name: 'United States'... }, { code: 'GB', name: 'United Kingdom'... }]

Available Functions

getCountryByCode(code: CountryCode)

Returns complete country information for a given ISO 3166-1 alpha-2 code.

const country = getCountryByCode('GB');
// => { 
//   code: 'GB',
//   name: 'United Kingdom',
//   alpha3: 'GBR',
//   callingCode: '+44',
//   flag: '🇬🇧'
// }

getCountryName(code: CountryCode)

Returns the country name for a given country code.
```
const name = getCountryName('US'); // => 'United States'
```
getAlpha3Code(code: CountryCode)

Returns the ISO 3166-1 alpha-3 code for a country.
```
const alpha3 = getAlpha3Code('US'); // => 'USA'
```
getCallingCode(code: CountryCode)

Gets the international calling code for a country.
```
const callingCode = getCallingCode('US'); // => '+1'
```
getCountryFlag(code: CountryCode)

Returns the flag emoji for a country.
```
const flag = getCountryFlag('JP'); // => '🇯🇵'
```

searchCountries(query?: string, options?: CountrySearchOptions)

Search countries by name or code with configurable options.

// Basic search
const results = searchCountries('united');

// With options
const exactMatch = searchCountries('united', { 
  exact: true,
  limit: 2,
  includeCodes: true 
});

getAllCountries()

Returns an array of all available countries with complete information.

const allCountries = getAllCountries();
// => [
//   { code: 'AD', name: 'Andorra', ... },
//   { code: 'AE', name: 'United Arab Emirates', ... },
//   ...
// ]

isValidCountryCode(code: string)

Validates if a string is a valid ISO 3166-1 alpha-2 country code.

isValidCountryCode('US'); // => true
isValidCountryCode('XX'); // => false
isValidCountryCode(''); // => false

isValidCallingCode(callingCode: string)

Validates if a string matches the format of an international calling code.

isValidCallingCode('+1'); // => true
isValidCallingCode('44'); // => false
isValidCallingCode('+12345'); // => false

getCountriesByCallingCode(callingCode: string)

Returns all countries that share a specific calling code.

const countries = getCountriesByCallingCode('+1');
// Returns countries like US, Canada, etc. that use +1

Types

type CountryCode = string; // ISO 3166-1 alpha-2 code

interface Country {
    code: CountryCode;  // ISO 3166-1 alpha-2 code
    name: string;       // Official country name
    alpha3: string;     // ISO 3166-1 alpha-3 code
    callingCode: string; // International calling code with + prefix
    flag: string;       // Unicode flag emoji
}

interface CountrySearchOptions {
    limit?: number;         // Maximum number of results to return
    exact?: boolean;        // Whether to match exactly (default: false)
    includeCodes?: boolean; // Whether to search by country codes as well (default: true)
}