libphonenumber-js

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

See Demo

If you’re trying to build a React component with it, take a look at react-phone-number-input.

LibPhoneNumber

Google's libphonenumber is an ultimate phone number formatting and parsing library developed by Google for Android phones. It is written in C++ and Java, and, while it has an official autogenerated javascript port, that port is tightly coupled to Google's closure javascript framework, and, when compiled into a bundle, weighs about 550 kB (350 kB code + 200 kB metadata).

With many websites today asking for user's phone number, the internet could benefit from a simpler and smaller library that would just get the parsing and formatting right, and that's what libphonenumber-js is.

Difference from Google's libphonenumber

• Smaller footprint: 145 kB (65 kB code + 80 kB sufficient metadata) vs the original Google's 550 kB (350 kB code + 200 kB full metadata).

• Can search for phone numbers in text (Google's autogenerated javascript port can't).

• Aims at parsing and formatting people's phone numbers while skipping all other "special" cases like:

  • Emergency phone numbers like 911.

  • "Short codes": short SMS-only numbers like 12345.

  • Numbers starting with a *, like *555.

  • Alphabetic phone numbers like 1-800-GOT-MILK: people don't input their phone numbers like that, it's only used in advertisement.

  • "Two-in-one" phone numbers with "combined" extensions like (530) 583-6985 x302/x2303 that in fact represent two separate phone numbers, because the library can only return a single phone number when parsing a string.

  • Overall, doesn't support formatting non-"conventional" numbers like numbers with the "area code" omitted or "alternative" "short" numbers like Australian 13-smart numbers. For example, when dialing phone numbers within the same "area", people sometimes skip the "area code", and dial, say, 456-789 instead of (123) 456-789. Google's libphonenumber supports formatting such numbers (with "area code" omitted) because it is used for dialing on the Android phone operating system. Because libphonenumber-js isn't a phone operating system and is not used for actual dialing — only for inputting internationally-dialable personal phone numbers — it doesn't format such "short" phone numbers because it doesn't need to support those.

  • Any other "miscellaneous" cases that're considered irrelevant for the task.

• Doesn't provide "geolocation" by a phone number.

• Doesn't use hyphens or brackets when formatting international phone numbers, only whitespace (seems more logical this way).

• Doesn't set .country to "001" when parsing "non-geographic" phone numbers (like mobile satellite communications services). Instead, .country is undefined in those cases, and a developer can call .isNonGeographic() method of the PhoneNumber instance to find out whether the parsed phone number is a "non-geographic" one.

• Doesn't provide the equivalent of libphonenumber's formatNumberForMobileDialing() function that formats a number for dialing using a mobile phone within the country: dialing local numbers from a mobile phone is a bit more complicated in some countries like Brazil or Colombia where they require adding "carrier codes" when making a call. Since libphonenumber-js is not a dialing library (we're not Android phone operaing system), it doesn't prepend any "carrier codes" when formatting phone numbers, though it does parse such "carrier codes" correctly.

GitHub

On March 9th, 2020, GitHub, Inc. silently banned my account (erasing all my repos, issues and comments, even in my employer's private repos) without any notice or explanation. Because of that, all source codes had to be promptly moved to GitLab. The GitHub repo is now only used as a backup (you can star the repo there too), and the primary repo is now the GitLab one. Issues can be reported in any repo.

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.

Use

Parse phone number

import parsePhoneNumber from 'libphonenumber-js'

const phoneNumber = parsePhoneNumber(' 8 (800) 555-35-35 ', 'RU')
if (phoneNumber) {
  phoneNumber.country === 'RU'
  phoneNumber.number === '+78005553535'
  phoneNumber.isPossible() === true
  phoneNumber.isValid() === true
  // Note: `.getType()` requires `/max` metadata: see below for an explanation.
  phoneNumber.getType() === 'TOLL_FREE'
}

Validate phone number

import {
  isPossiblePhoneNumber,
  isValidPhoneNumber,
  validatePhoneNumberLength
} from 'libphonenumber-js'

isPossiblePhoneNumber('8 (800) 555-35-35', 'RU') === true
isValidPhoneNumber('8 (800) 555-35-35', 'RU') === true

validatePhoneNumberLength('8 (800) 555', 'RU') === 'TOO_SHORT'
validatePhoneNumberLength('8 (800) 555-35-35', 'RU') === undefined // Length is valid.

isPossiblePhoneNumber() only validates phone number length, while isValidPhoneNumber() validates both phone number length and the actual phone number digits.

validatePhoneNumberLength() is just a more detailed version of isPossiblePhoneNumber() — if the phone number length is invalid, it returns the actual reason: TOO_SHORT, TOO_LONG, etc.

Format phone number

import parsePhoneNumber from 'libphonenumber-js'

const phoneNumber = parsePhoneNumber('+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
// }]

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

This library provides different "metadata" sets, "metadata" being a list of phone number parsing and formatting rules for all countries. The complete list of those 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 145 kilobytes in size (libphonenumber-js/metadata.max.json). Choose this when you need the most strict version of isValid(), or if you need to detect phone number type ("fixed line", "mobile", etc).

• min — (default) The smallest metadata set, is about 80 kilobytes in size (libphonenumber-js/metadata.min.json). Choose this by default: when you don't need to detect phone number type ("fixed line", "mobile", etc), or when a basic version of isValid() is enough. The min metadata set doesn't contain the regular expressions for phone number digits validation (via .isValid()) and detecting phone number type (via .getType()) for most countries. In this case, .isValid() still performs some basic phone number validation (for example, checks phone number length), but it doesn't validate phone number digits themselves the way max metadata validation does.

• mobile — The complete metadata set for dealing with mobile numbers only, is about 95 kilobytes in size (libphonenumber-js/metadata.mobile.json). Choose this when you need max metadata and when you only accept mobile numbers. Other phone number types will still be parseable, but they won't be recognized as being "valid" (.isValid() will return false).

To use a particular metadata set, simply import functions from a relevant sub-package:

• libphonenumber-js/max
• libphonenumber-js/min
• libphonenumber-js/mobile

Importing functions directly from libphonenumber-js effectively results in using the min metadata.

Sometimes (rarely) not all countries are needed, and in those cases 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-packaged with any default metadata set and instead accepts metadata as the last argument of each exported function.

Definitions

Country code

A "country code" is a two-letter ISO country code (like US). <!-- or a special 001 country code used for "non-geographic entities" (as per [Google's libphonenumber library](http