libphonenumber-js

A simpler and smaller rewrite of Google Android's libphonenumber library in javascript.

See Demo

LibPhoneNumber

libphonenumber is a phone number formatting and parsing library released by Google, originally developed for (and currently used in) Google's Android mobile phone operating system.

libphonenumber-js is a "lighter" pure javascript rewrite of the original libphonenumber library (written in C++ and Java because those are the programming languages used in Android OS). While libphonenumber has an official autogenerated javascript port which is being maintained by Google, it is tightly coupled to Google's closure javascript utility framework. It can still be compiled into one gigantic bundle which weighs 530 kilobytes (330 kB code + 200 kB metadata) — quite a size for a simple phone number input field on a casual website.

Difference from Google's libphonenumber

• Smaller footprint: 130 kilobytes (55 kB code + 75 kB sufficient metadata) vs the original Google's 530 kilobytes (330 kB code + 200 kB full metadata).
• Can search for phone numbers in text (Google's autogenerated javascript port can't).
• Doesn't parse alphabetic phone numbers like 1-800-GOT-MILK.
• Doesn't parse or format special "local"-only phone numbers: numbers specific to a "local" area (for example, a city) with the "area code" omitted (like 456-789 with the "area code" (123) omitted vs. the full (123) 456-789 number), emergency phone numbers like 911, "short codes" (short SMS-only numbers), numbers starting with a * (like *555), etc.
• Doesn't use hyphens and brackets when formatting international phone numbers (looks cleaner).
• Doesn't use the "001" country code for "non-geographic" phone numbers. Instead, PhoneNumber class has an .isNonGeographic() method.

Install

via npm

$ npm install libphonenumber-js --save

via yarn

$ yarn add libphonenumber-js

If you're not using a bundler then use a standalone version from a CDN.

"min" vs "max" vs "mobile" vs "core"

This library requires choosing a "metadata" set to be used, "metadata" being a list of phone number parsing and formatting rules for all countries. The complete list of rules is huge, so this library provides a way to optimize bundle size by choosing between max, min, mobile and custom metadata:

• max — The complete metadata set, is about 140 kilobytes in size (libphonenumber-js/metadata.full.json). Choose this when you need a strict version of isValidPhoneNumber(value) function, or if you need to get phone number type (fixed line, mobile, etc).

• min — (default) The smallest metadata set, is about 75 kilobytes in size (libphonenumber-js/metadata.min.json). Doesn't contain regular expressions for advanced phone number validation (.isValid()) and determining phone number type (.getType()) for most countries. Some simple phone number validation via .isValid() still works (basic length check, etc), it's just that it's loose compared to the "advanced" validation (not so strict). Choose this by default: when you don't need to get phone number type (fixed line, mobile, etc), or when a non-strict version of isValidPhoneNumber(value) function is enough.

• mobile — The complete metadata set for dealing with mobile numbers only, is about 105 kilobytes in size (libphonenumber-js/metadata.mobile.json). Choose this when you only work with mobile numbers and a strict version of isValidPhoneNumber(value) function is required for validating mobile numbers.

To use a particular metadata set import functions from the relevant sub-package: libphonenumber-js/max, libphonenumber-js/min or libphonenumber-js/mobile.

Importing functions directly from libphonenumber-js results in using the min metadata which means loose (non-strict) phone number validation via .isValid() and no getting phone number type via .getType() for most countries.

Sometimes (rarely) not all countries are needed and in those cases the developers may want to generate their own "custom" metadata set. For those cases there's libphonenumber-js/core sub-package which doesn't come pre-wired with any default metadata and instead accepts the metadata as the last argument of each exported function.

Use

Parse phone number

import { parsePhoneNumberFromString } from 'libphonenumber-js'

const phoneNumber = parsePhoneNumberFromString('Phone: 8 (800) 555 35 35.', 'RU')
if (phoneNumber) {
  phoneNumber.country === 'RU'
  phoneNumber.number === '+78005553535'
  phoneNumber.isValid() === true
  phoneNumber.getType() === 'TOLL_FREE'
}

Format phone number

import { parsePhoneNumberFromString } from 'libphonenumber-js'

const phoneNumber = parsePhoneNumberFromString('+12133734253')

phoneNumber.formatInternational() === '+1 213 373 4253'
phoneNumber.formatNational() === '(213) 373-4253'
phoneNumber.getURI() === 'tel:+12133734253'

"As You Type" formatter

import { AsYouType } from 'libphonenumber-js'

new AsYouType().input('+12133734')
// Outputs: '+1 213 373 4'

new AsYouType('US').input('2133734')
// Outputs: '(213) 373-4'

Full-text search

import { findPhoneNumbersInText } from 'libphonenumber-js'

findPhoneNumbersInText(`
  For tech support call +7 (800) 555-35-35 internationally
  or reach a local US branch at (213) 373-4253 ext. 1234.
`, 'US')

// Outputs:
//
// [{
//   number: PhoneNumber {
//     country: 'RU',
//     countryCallingCode: '7',
//     number: '+78005553535',
//     nationalNumber: '8005553535'
//   },
//   startsAt : 22,
//   endsAt   : 40
// }, {
//   number: PhoneNumber {
//     country: 'US',
//     countryCallingCode: '1',
//     number: '+12133734253',
//     nationalNumber: '2133734253',
//     ext: '1234'
//   },
//   startsAt : 86,
//   endsAt   : 110
// }]

Definitions

Country code

"Country code" means either a two-letter ISO country code (like US).

Non-geographic

There're several calling codes that don't belong to any country:

• +800 — Universal International Toll Free Number
• +808 — Universal International Shared Cost Number
• +870 — Inmarsat Global Limited
• +878 — Universal Personal Telecommunications
• +881 — Global Mobile Satellite System
• +882 and +883 — International Networks
• +888 — United Nations Office for the Coordination of Humanitarian Affairs
• +979 — International Premium Rate Service

Such phone numbering plans are called "non-geographic", and their phone numbers have country set to undefined.

National (significant) number

"National (significant) number" are the national phone number digits (without "national prefix"). For example, +1 213 373 4253 (or (213) 373-4253 in national format) is a US phone number and its national (significant) number is 213 373 4253. Another example is +33 1 45 45 32 45 (or 01 45 45 32 45 in national format) which is a French phone number where they add 0 "national prefix" when writing phone numbers in national format; in this case the national (significant) number is 1 45 45 32 45.

Country calling code

"Country calling code" are the digits between the + and the national (significant) number when the number is written in international format. E.g. for US country calling code is 1 and for France it's 33. Several countries can share the same "country calling code", e.g. NANPA countries like USA and Canada sharing the same 1 country calling code.

API

parsePhoneNumberFromString(string, [options or defaultCountry]): PhoneNumber

Parses a phone number from string.

import { parsePhoneNumberFromString } from 'libphonenumber-js'

const phoneNumber = parsePhoneNumberFromString('Call: (213) 373-42-53 ext. 1234.', 'US')
if (phoneNumber) {
  console.log(phoneNumber.formatNational())
}

Returns an instance of PhoneNumber class, or undefined if no phone number could be parsed: for example, when the string contains no phone number, or the phone number starts with a non-existent country calling code, etc.

Available options:

• defaultCountry — Default country for parsing national numbers. Instead of passing options.defaultCountry one could pass defaultCountry argument directly.

• defaultCallingCode — Default calling code for parsing national numbers. Some numbering plans are for "non-geographic numbering plans" and they don't have a country code, so defaultCountry can't be specified for them.

If a developer wants to know the exact reason why the phone number couldn't be parsed then they can use parsePhoneNumber() function which throws the exact error:

import { parsePhoneNumber, ParseError } from 'libphonenumber-js'

try {
  const phoneNumber = parsePhoneNumber('Call: (213) 373-42-53 ext. 1234.', 'US')
} catch (error) {
  if (error instanceof ParseError) {
    // Not a phone number, non-existent country, etc.
    console.log(error.message)
  } else {
    throw error
  }
}

• INVALID_COUNTRY — When defaultCountry doesn't exist (parsePhoneNumber('(111) 222-3333', 'XX')) or isn't supported by this library, or when parsing non-international number without a defaultCountry (parsePhoneNumber('(111) 222-3333')), or when international number country calling code doesn't exist (parsePhoneNumber('+9991112223333')).

• NOT_A_NUMBER — When no phone number was found. For example, when there are no digits ("abcde") or when there's not enough digits (parsePhoneNumber('2', 'US'), parsePhoneNumber('+1')).

• TOO_LONG — When national (significant) number is too long (17 digits max) or when the string being parsed is too long (250 characters max).

• TOO_SHORT — When national (significant) number is too short (for ex. 1 digit).

PhoneNumber

PhoneNumber class instance has the following properties:

• number: string — The phone number in E.164 format. Example: "+12133734253".
• countryCallingCode: string — The country calling code. Example: "1".
• nationalNumber: string — The national (significant) number. Example: "2133734253".
• country: string? — The country code. Example: "US". Will be undefined when no country could be derived from the phone number. For example, when several countries have the same countryCallingCode and the nationalNumber doesn't look like it belongs to any of them. Or when a number belongs to a non-geographic numbering plan.
• ext: string? — The phone number extension, if any. Example: "1234".
• carrierCode: string? — The "carrier code", if any. Example: "15". "Carrier codes" are only used in Colombia and Brazil and only when dialing within those countries from a mobile phone to a fixed line number.

PhoneNumber class instance provides the following methods:

format(format: string, [options]): string

Formats the phone number into a string according to a format.

Available formats:

• NATIONAL — Example: "(213) 373-4253"
• INTERNATIONAL — Example: "+1 213 373 4253"
• E.164 — Example: "+12133734253"
• RFC3966 (the phone number URI) — Example: "tel:+12133734253;ext=123"
• IDD — "Out-of-country" dialing format. Example: "01178005553535" for +7 800 555 35 35 being called out of options.fromCountry === "US". If no options.fromCountry was passed or if there's no default IDD prefix for options.fromCountry then returns undefined. Pass options.humanReadable: true for a human-readable output (same output as Google liphonenumber's formatOutOfCountryCallingNumber()).

Available options:

• formatExtension(number, extension) — Formats number and extension into a string. By default returns ${number} ext. ${extension} for almost all countries with rare exceptions of some special cases like ${number} x${extension} for UK.

• humanReadable: Boolean — Is only used for IDD formatting.

• nationalPrefix: Boolean — Some phone numbers can be formatted both with national prefix and without it. In such cases the library defaults to "with national prefix" (for legacy reasons). Pass nationalPrefix: false option to force formatting without national prefix in such cases.

Examples:

import { parsePhoneNumberFromString } from 'libphonenumber-js'

const phoneNumber = parsePhoneNumberFromString('+12133734253')

phoneNumber.format("NATIONAL") === '(213) 373-4253'
phoneNumber.format("INTERNATIONAL") === '+1 213 373 4253'
phoneNumber.format("RFC3966") === 'tel:+12133734253'

// Aliases
phoneNumber.formatNational() === phoneNumber.format("NATIONAL")
phoneNumber.formatInternational() === phoneNumber.format("INTERNATIONAL")
phoneNumber.getURI() === phoneNumber.format("RFC3966")

isPossible(): boolean

Checks if the phone number is "possible". Only checks the phone number length, doesn't check the number digits against any regular expressions.

isValid(): boolean

Checks if the phone number is "valid". First checks the phone number length and then checks the phone number digits against all available regular expressions.

By default the library uses "minimal" metadata which is only 75 kilobytes in size but also doesn't include the precise validation regular expressions resulting in less strict validation rules (some very basic validation like length check is still included for each country). If you don't mind the extra 65 kilobytes of metadata then use "full" metadata instead (140 kilobytes). Google's library always uses "full" metadata so it will yield different isValidNumber() results compared to the "minimal" metadata used by default in this library.

import { parsePhoneNumberFromString as parseMin } from 'libphonenumber-js'
import { parsePhoneNumberFromString as parseMax } from 'libphonenumber-js/max'
import { parsePhoneNumberFromString as parseMobile } from 'libphonenumber-js/mobile'

// Mobile numbers in Singapore starting from `8`
// can only have the second digit in the range of `0..8`.
// Here the second digit is `9` which makes it an invalid mobile number.
// This is a "strict" (advanced) validation rule and is
// not included in the (default) "min" bundle.

// The basic number length check passes (`8..11`) and the
// "loose" national number validation regexp check passes too:
// `(?:1\d{3}