Core phone number parsing, formatting, and validation functionality provided by the PhoneNumberUtil class. This is the primary interface for most phone number operations in google-libphonenumber.
The main utility class that provides phone number operations. Uses singleton pattern - access via getInstance().
/**
* Main utility class for phone number operations
* @singleton Access via PhoneNumberUtil.getInstance()
*/
class PhoneNumberUtil {
/**
* Get the singleton instance of PhoneNumberUtil
* @returns {PhoneNumberUtil} The singleton instance
*/
static getInstance(): PhoneNumberUtil;
}Parse phone numbers from strings into PhoneNumber objects for further processing.
/**
* Parse a string and return it in proto buffer format.
* @param {string} numberToParse - The number to parse
* @param {string} defaultRegion - ISO 3166-1 alpha-2 region code for context
* @returns {PhoneNumber} Parsed phone number object
* @throws {Error} If the string cannot be parsed
*/
parse(numberToParse: string, defaultRegion: string): PhoneNumber;
/**
* Parse a string and return it in proto buffer format while keeping the raw input value.
* @param {string} numberToParse - The number to parse
* @param {string} defaultRegion - ISO 3166-1 alpha-2 region code for context
* @returns {PhoneNumber} Parsed phone number object with raw input preserved
* @throws {Error} If the string cannot be parsed
*/
parseAndKeepRawInput(numberToParse: string, defaultRegion: string): PhoneNumber;Usage Examples:
const phoneUtil = PhoneNumberUtil.getInstance();
// Basic parsing
const number1 = phoneUtil.parse('+1-202-456-1414', 'US');
const number2 = phoneUtil.parse('202-456-1414', 'US');
// Parse and keep raw input (useful for formatting in original style)
const numberWithRaw = phoneUtil.parseAndKeepRawInput('(202) 456-1414', 'US');
console.log(numberWithRaw.getRawInput()); // "(202) 456-1414"Format parsed phone numbers in various international and national formats.
/**
* Format a phone number in the specified format using default rules.
* @param {PhoneNumber} number - The parsed phone number to format
* @param {PhoneNumberFormat} numberFormat - The format to use
* @returns {string} The formatted phone number string
*/
format(number: PhoneNumber, numberFormat: PhoneNumberFormat): string;
/**
* Format a phone number using the original phone number format that the number is parsed from.
* @param {PhoneNumber} number - The parsed phone number (must have raw input)
* @param {string} regionCallingFrom - The region the call is being placed from
* @returns {string} The formatted phone number in original format
*/
formatInOriginalFormat(number: PhoneNumber, regionCallingFrom: string): string;
/**
* Format a phone number for out-of-country dialing purposes.
* @param {PhoneNumber} number - The parsed phone number to format
* @param {string} regionCallingFrom - The region the call is being placed from
* @returns {string} The formatted phone number for international dialing
*/
formatOutOfCountryCallingNumber(number: PhoneNumber, regionCallingFrom: string): string;Usage Examples:
const phoneUtil = PhoneNumberUtil.getInstance();
const number = phoneUtil.parseAndKeepRawInput('202-456-1414', 'US');
// Different formatting options
console.log(phoneUtil.format(number, PhoneNumberFormat.E164));
// => "+12024561414"
console.log(phoneUtil.format(number, PhoneNumberFormat.INTERNATIONAL));
// => "+1 202-456-1414"
console.log(phoneUtil.format(number, PhoneNumberFormat.NATIONAL));
// => "(202) 456-1414"
console.log(phoneUtil.formatInOriginalFormat(number, 'US'));
// => "(202) 456-1414" (matches original input format)
console.log(phoneUtil.formatOutOfCountryCallingNumber(number, 'CH'));
// => "00 1 202-456-1414" (Swiss international dialing format)Validate whether phone numbers are properly formatted and valid for specific regions.
/**
* Test whether a phone number matches a valid pattern.
* @param {PhoneNumber} number - The parsed phone number to validate
* @returns {boolean} True if the number is valid
*/
isValidNumber(number: PhoneNumber): boolean;
/**
* Test whether a phone number is valid for a certain region.
* @param {PhoneNumber} number - The parsed phone number to validate
* @param {string} regionCode - ISO 3166-1 alpha-2 region code
* @returns {boolean} True if the number is valid for the region
*/
isValidNumberForRegion(number: PhoneNumber, regionCode: string): boolean;
/**
* Returns true if the number is possible (contains area code and country code)
* or if it could be a possible local number (with country code but missing area code).
* @param {PhoneNumber} number - The parsed phone number to check
* @returns {boolean} True if the number is possible
*/
isPossibleNumber(number: PhoneNumber): boolean;Usage Examples:
const phoneUtil = PhoneNumberUtil.getInstance();
const validNumber = phoneUtil.parse('+1-202-456-1414', 'US');
const invalidNumber = phoneUtil.parse('+1-555-0123', 'US');
// Validation checks
console.log(phoneUtil.isValidNumber(validNumber)); // => true
console.log(phoneUtil.isValidNumber(invalidNumber)); // => false
console.log(phoneUtil.isValidNumberForRegion(validNumber, 'US')); // => true
console.log(phoneUtil.isValidNumberForRegion(validNumber, 'CA')); // => false
console.log(phoneUtil.isPossibleNumber(validNumber)); // => trueExtract information about phone numbers including type and geographic region.
/**
* Get the type of a valid phone number.
* @param {PhoneNumber} number - The parsed phone number to analyze
* @returns {PhoneNumberType} The type of the phone number
*/
getNumberType(number: PhoneNumber): PhoneNumberType;
/**
* Return the region where a phone number is from.
* @param {PhoneNumber} number - The parsed phone number to analyze
* @returns {string} ISO 3166-1 alpha-2 region code or null
*/
getRegionCodeForNumber(number: PhoneNumber): string;Usage Examples:
const phoneUtil = PhoneNumberUtil.getInstance();
const number = phoneUtil.parse('+1-202-456-1414', 'US');
// Analyze the number
console.log(phoneUtil.getNumberType(number));
// => PhoneNumberType.FIXED_LINE_OR_MOBILE
console.log(phoneUtil.getRegionCodeForNumber(number));
// => "US"Phone number parsing can throw errors for invalid input. Always wrap parsing operations in try-catch blocks when dealing with user input:
const phoneUtil = PhoneNumberUtil.getInstance();
try {
const number = phoneUtil.parse(userInput, defaultRegion);
// Process valid number
} catch (error) {
// Handle parsing error
console.error('Invalid phone number:', error.message);
}PhoneNumberUtil.getInstance() returns a singleton, so it's safe to call repeatedlyPhoneNumber objects can be reused for multiple operationsparseAndKeepRawInput() only when you need to format in the original style