⚠️ DEPRECATED

This package is no longer maintained.

Please use libphonenumber-js instead. See: https://www.npmjs.com/package/libphonenumber-js

Original README below:

country-phone-codes

A modern, TypeScript-first library providing a clean, typed mapping of ISO 3166-1 alpha-2 country codes to their international phone codes (e.g., US → +1, IN → +91).

Features

• 🌍 Complete dataset: Maps all ISO 3166-1 alpha-2 country codes to their international phone code
• 📖 Data transparency: All country-phone code mappings embedded directly in the library
• 🔄 Bidirectional lookups: Find phone codes by country or countries by phone code
• 🔍 Validation & normalization: Clean and validate phone code strings
• 📦 Zero runtime dependencies: Lightweight, embedded dataset
• 🔢 First-class TypeScript: Written in TypeScript with comprehensive type definitions
• 📟 Modern exports: Supports both ESM and CommonJS
• ⚡ Tree-shakable: Import only what you need
• 🧪 Well-tested: High test coverage

Installation

npm install country-phone-codes
# or
yarn add country-phone-codes
# or
pnpm add country-phone-codes

Usage

import {
  countryPhoneCodesMap,
  getPhoneCode,
  getCountriesByPhoneCode,
  getAllPhoneCodes,
  isValidPhoneCode,
  normalizePhoneCode
} from 'country-phone-codes';

// Get a phone code for a country
const usCode = getPhoneCode('US'); // '+1'
const indiaCode = getPhoneCode('in'); // '+91' (case-insensitive)

// Find all countries that use a specific phone code
const plusOneCountries = getCountriesByPhoneCode('+1');
// ['US', 'CA', 'AG', 'AI', 'AS', 'BB', 'BM', 'BS', 'DM', 'DO', ...]

// Normalize phone code inputs
normalizePhoneCode('1'); // '+1'
normalizePhoneCode('+44'); // '+44'
normalizePhoneCode('(0049) 123'); // '+49123'
normalizePhoneCode('0091 12-34-56'); // '+91123456'

// Check if a phone code is valid
isValidPhoneCode('+1'); // true
isValidPhoneCode('44'); // true (auto-normalized)
isValidPhoneCode('+999'); // false

// Get all phone codes
const allCodes = getAllPhoneCodes();
// ['+1', '+7', '+20', '+27', '+30', '+31', '+32', '+33', '+34', ...]

// Access raw data directly
console.log(countryPhoneCodesMap);
// { US: '+1', CA: '+1', GB: '+44', ... }

API Reference

Data

countryPhoneCodesMap

The primary data object mapping ISO 3166-1 alpha-2 country codes (keys) to their international phone codes (values).

// Type: Readonly<Record<string, string>>
const map = countryPhoneCodesMap;
console.log(map['US']); // '+1'
console.log(map['GB']); // '+44'

Functions

getPhoneCode(countryCode: string): string | undefined

Gets the international phone code for a given country code.

• Parameters:
  • countryCode: ISO 3166-1 alpha-2 country code (case-insensitive)
• Returns: The international phone code with '+' prefix, or undefined if not found

getPhoneCode('US'); // '+1'
getPhoneCode('in'); // '+91'
getPhoneCode('XYZ'); // undefined

getCountriesByPhoneCode(phoneCode: string): string[]

Gets all countries that use a specific phone code.

• Parameters:
  • phoneCode: The international phone code to look up (automatically normalized)
• Returns: Array of ISO 3166-1 alpha-2 country codes that use this phone code, or empty array if none

getCountriesByPhoneCode('+1'); // ['US', 'CA', 'AG', ...]
getCountriesByPhoneCode('44'); // ['GB', 'IM']
getCountriesByPhoneCode('+999'); // []

getAllPhoneCodes(): string[]

Gets an array of all unique international phone codes.

• Returns: Array of all unique phone codes in the dataset

getAllPhoneCodes(); // ['+1', '+7', '+20', '+27', ...]

isValidPhoneCode(phoneCode: string): boolean

Checks if the provided string is a valid international phone code.

• Parameters:
  • phoneCode: The phone code to validate (automatically normalized)
• Returns: true if valid, false otherwise

isValidPhoneCode('+1'); // true
isValidPhoneCode('44'); // true
isValidPhoneCode('+999'); // false

normalizePhoneCode(code: string): string | undefined

Normalizes a phone code to ensure it has the proper format.

• Parameters:
  • code: The phone code string to normalize
• Returns: The normalized phone code or undefined if it can't be reasonably normalized

normalizePhoneCode('1'); // '+1'
normalizePhoneCode('+44'); // '+44'
normalizePhoneCode('(0049) 123'); // '+49123'
normalizePhoneCode('0091 12-34-56'); // '+91123456'

Types

The library exports the following TypeScript types:

type CountryCodeA2 = string; // ISO 3166-1 alpha-2 country code
type InternationalPhoneCode = string; // Phone code with '+' prefix
interface CountryPhoneCodeMapData {
  [countryCode: CountryCodeA2]: InternationalPhoneCode;
}

Use Cases

• 📝 Form validation for international phone numbers
• 🌐 User registration flows with country selection
• 📱 Telecom and communications applications
• 🔍 Data enrichment for contact databases
• 🧩 Integration with other internationalization libraries

JSON Data

If you need direct access to the JSON data, you can import it:

import countryPhoneCodesMap from 'country-phone-codes/json';

License

MIT