libphonenumber-js


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

Parse and format personal phone numbers.

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 deal with parsing or formatting personal phone numbers, and that's what libphonenumber-js is.

Differences 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).

* Comes with TypeScript definitions.

* Can search for phone numbers in text. Google's autogenerated javascript port doesn't provide such feature for some reason.

* Focuses on parsing and formatting personal phone numbers while skipping any other "special" cases like:

* Emergency phone numbers like 911.

* "Short codes" — short SMS-only numbers like 12345.

Numbers starting with an . For example, 555 is used in New Zeland to report non-urgent traffic incidents. Or, in Israel, certain advertising numbers start with a .

* Australian 13-smart numbers, which are a "catchy" "short" form of regular "landline" numbers and are mainly used in advertisement.

* Alphabetic phone numbers like 1-800-GOT-MILK. People don't input their phone numbers like that. It was only used in advertisement in the days of push-button telephones.

* "Two-in-one" phone numbers with "combined" extensions like (530) 583-6985 x302/x2303. Phone numbers like that actually represent two separate phone numbers, so it's not clear which one to pick or how to return both at the same time.

* Local numbers with the "area code" omitted. For example, when dialing phone numbers within the same "area", people sometimes skip the "area code", and dial, say, just 456-789 instead of proper (123) 456-789. This all is considered a relic of the past. In the modern world, there're no "local areas" and anyone could call everyone else around the world.

* Doesn't provide "geolocation" feature when it can tell a city by a phone number.

* Doesn't use hyphens or brackets when formatting phone numbers in international format. Instead, whitespace is used. The rationale is that brackets aren't relevant in international context because there're no "local areas", and hyphens aren't used because whitespace just looks cleaner.

* Doesn't set .country to "001" when parsing "non-geographic" phone numbers, like mobile satellite communications services. Instead, .country is set to undefined in those cases, and instead 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 from a mobile phone within the same country. This feature may be required for dialing local numbers from a mobile phone in some countries like Brazil or Colombia where they require adding "carrier codes" when making such calls. Since libphonenumber-js is not a dialing library (we're not Android phone operaing system), it doesn't prepend any "carrier codes" when formatting such phone numbers, though it does parse such "carrier codes" correctly.

* Fixed a small bug when Canadian numbers +1310xxxx wheren't considered possible.

Install

via npm

``sh
$ npm install libphonenumber-js --save
`

via yarn

`sh
$ yarn add libphonenumber-js
`

Alternatively, one could include it on a web page directly via a