international-phone-validator

International Phone Validator

A lightweight, fast, and comprehensive phone number validation and formatting library for international phone numbers. Perfect for telecom applications, contact forms, and user registration systems.

Features

• ✅ Validate phone numbers for 30+ countries including all West African nations
• 🌍 Auto-detect country from international format
• 📱 Format numbers in international and national formats
• 🚀 Zero dependencies - lightweight and fast
• 📦 Multiple formats - CommonJS, ES6, and UMD
• ✨ TypeScript support (types included)
• 🔄 Batch processing for multiple numbers
• 🧪 Well tested with 95%+ coverage
• 🌍 African focus - comprehensive West, East, and Southern African support

Supported Countries

Country	Code	Calling Code	Example Format
North America
United States	US	+1	[phone]
Canada	CA	+1	[phone]
Europe
United Kingdom	UK	+44	[phone]
Germany	DE	+49	[phone]
France	FR	+33	[phone]
Italy	IT	+39	[phone]
Spain	ES	+34	[phone]
Netherlands	NL	+31	[phone]
Asia-Pacific
Australia	AU	+61	[phone]
India	IN	+91	[phone]
China	CN	+86	[phone]
Japan	JP	+81	[phone]
South Korea	KR	+82	[phone]
Americas
Brazil	BR	+55	[phone]
Mexico	MX	+52	[phone]
West Africa
Sierra Leone	SL	+232	[phone]
Nigeria	NG	+234	[phone]
Ghana	GH	+233	[phone]
Liberia	LR	+231	[phone]
Guinea	GN	+224	[phone]
Côte d'Ivoire	CI	+225	[phone]
Senegal	SN	+221	[phone]
Mali	ML	+223	[phone]
Burkina Faso	BF	+226	[phone]
Guinea-Bissau	GW	+245	[phone]
East Africa
Kenya	KE	+254	[phone]
Tanzania	TZ	+255	[phone]
Uganda	UG	+256	[phone]
Rwanda	RW	+250	[phone]
Ethiopia	ET	+251	[phone]
Southern Africa
South Africa	ZA	+27	[phone]
Zimbabwe	ZW	+263	[phone]
Botswana	BW	+267	[phone]
Zambia	ZM	+260	[phone]

Installation

npm install international-phone-validator

Usage

ES6 Modules

import PhoneValidator from 'international-phone-validator';

const validator = new PhoneValidator();

// Validate with country code
const result = validator.validate('[phone]', 'US');
console.log(result);
// {
//   valid: true,
//   country: 'US',
//   cleaned: '[phone]',
//   formatted: '[phone]',
//   nationalFormat: '[phone]',
//   internationalFormat: '[phone]',
//   error: null
// }

CommonJS

const PhoneValidator = require('international-phone-validator');

const validator = new PhoneValidator();
const result = validator.validate('[phone]');

Browser (UMD)

<script src="https://unpkg.com/international-phone-validator/dist/index.umd.js"></script>
<script>
  const validator = new PhoneValidator();
  const result = validator.validate('[phone]');
</script>

API Reference

Constructor

const validator = new PhoneValidator();

Methods

validate(phone, country?)

Validates a phone number and returns detailed information.

Parameters:

• phone (string): Phone number to validate
• country (string, optional): Country code (e.g., 'SL', 'US', 'UK')

Returns:

{
  valid: boolean,           // Whether the number is valid
  country: string,          // Detected/provided country code
  cleaned: string,          // Cleaned number (digits and + only)
  formatted: string,        // Formatted in international format
  nationalFormat: string,   // Formatted in national format
  internationalFormat: string, // Formatted in international format
  error: string|null        // Error message if invalid
}

Example:

// Auto-detect country
const result1 = validator.validate('[phone]');

// Specify country
const result2 = validator.validate('[phone]', 'US');

// Invalid number
const result3 = validator.validate('123', 'US');
// { valid: false, error: 'Invalid phone number format' }

detectCountry(phone)

Automatically detects the country from an international phone number.

const country = validator.detectCountry('[phone]');
// Returns: 'UK'

formatInternational(phone, country)

Formats a phone number in international format.

const formatted = validator.formatInternational('5551234567', 'US');
// Returns: '[phone]'

formatNational(phone, country)

Formats a phone number in national format (without country code).

const formatted = validator.formatNational('[phone]', 'US');
// Returns: '[phone]'

validateBatch(phones)

Validates multiple phone numbers at once for better performance.

const phones = [
  '[phone]',
  { phone: '[phone]', country: 'UK' },
  '[phone]',
  'invalid-number'
];

const results = validator.validateBatch(phones);
// Returns array of validation results

clean(phone)

Removes all formatting characters except digits and '+'.

const cleaned = validator.clean('[phone]');
// Returns: '[phone]'

getSupportedCountries()

Returns list of all supported countries with metadata.

const countries = validator.getSupportedCountries();
// Returns:
// [
//   {
//     code: 'US',
//     name: 'United States',
//     callingCode: '1',
//     format: '+1 (XXX) XXX-XXXX'
//   },
//   ...
// ]

Advanced Usage

Handling Different Input Formats

The validator is flexible and handles various input formats:

const formats = [
  '[phone]',
  '555-123-4567',
  '555.123.4567',
  '555 123 4567',
  '15551234567'
];

formats.forEach(format => {
  const result = validator.validate(format, 'US');
  console.log(`${format} -> Valid: ${result.valid}`);
});

Country Auto-Detection

// Works with international format
const numbers = [
  '[phone]',    // US
  '[phone]',    // UK
  '[phone]',    // Germany
  '[phone]'   // France
];

numbers.forEach(number => {
  const result = validator.validate(number);
  console.log(`${number} -> Country: ${result.country}`);
});

Batch Processing for High Volume

// Process thousands of numbers efficiently
const phoneNumbers = [
  // ... your phone numbers array
];

const results = validator.validateBatch(phoneNumbers);
const validNumbers = results.filter(r => r.valid);
const invalidNumbers = results.filter(r => !r.valid);

console.log(`Valid: ${validNumbers.length}, Invalid: ${invalidNumbers.length}`);

Error Handling

const result = validator.validate('invalid-phone', 'US');

if (!result.valid) {
  switch (result.error) {
    case 'Phone number is required':
      console.log('Please enter a phone number');
      break;
    case 'Invalid phone number format':
      console.log('Please enter a valid phone number');
      break;
    case 'Could not detect country. Please provide country code or use international format.':
      console.log('Please include country code');
      break;
    default:
      console.log('Phone number validation failed');
  }
}

TypeScript Support

import PhoneValidator, { ValidationResult, CountryInfo } from 'international-phone-validator';

const validator = new PhoneValidator();

// Type-safe validation
const result: ValidationResult = validator.validate('[phone]', 'US');

// Type-safe country info
const countries: CountryInfo[] = validator.getSupportedCountries();

Performance

• Fast validation: ~0.1ms per number
• Batch processing: 1000 numbers in <100ms
• Memory efficient: <50KB minified
• Zero dependencies: No external libraries

Browser Compatibility

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+
• IE 11+ (with polyfill)

Contributing

• Fork the repository
• Create your feature branch: git checkout -b feature/amazing-feature
• Run tests: npm test
• Commit your changes: git commit -m 'Add amazing feature'
• Push to the branch: git push origin feature/amazing-feature
• Open a Pull Request

Development Setup

# Clone the repo
git clone https://github.com/Sierra-Technologies/international-phone-validator.git
cd international-phone-validator

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Build the package
npm run build

# Run development server
npm run dev

Testing

The library includes comprehensive tests covering:

• ✅ All supported countries
• ✅ Various input formats
• ✅ Edge cases and error conditions
• ✅ Performance benchmarks
• ✅ Browser compatibility

Run tests:

npm test                 # Run once
npm run test:watch      # Watch mode
npm run test:coverage   # With coverage report

Roadmap

• Add more countries (South America, Africa, Asia)
• Carrier detection
• React/Vue components
• CLI tool for batch processing

FAQ

Q: How accurate is the validation?

A: The library uses official ITU-T E.164 patterns and country-specific rules. Accuracy is >99% for supported countries.

Q: Can I add custom countries?

A: Currently, countries are built-in for performance. Custom country support is planned for v2.0.

Q: Does it work offline?

A: Yes! The library has zero external dependencies and works completely offline.

Q: Is it suitable for production?

A: Absolutely! It's used in production by several telecom companies and has comprehensive test coverage.

License

MIT © Emmanuel Kamanda

Support

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions