libphonenumber-js
Version:
A simpler (and smaller) rewrite of Google Android's libphonenumber library in javascript
1,092 lines (776 loc) • 68.7 kB
Markdown
# libphonenumber-js
[](https://www.npmjs.com/package/libphonenumber-js)
[](https://www.npmjs.com/package/libphonenumber-js)
[](https://coveralls.io/r/catamphetamine/libphonenumber-js?branch=master)
A simpler and smaller rewrite of Google Android's [`libphonenumber`](https://github.com/google/libphonenumber/blob/master/java/libphonenumber/) library in javascript.
[See Demo](https://catamphetamine.gitlab.io/libphonenumber-js/)
If you’re trying to build a React component with it, take a look at [`react-phone-number-input`](https://www.npmjs.com/package/react-phone-number-input).
## LibPhoneNumber
Google's [`libphonenumber`](https://github.com/googlei18n/libphonenumber) is an ultimate phone number formatting and parsing library developed by Google for [Android](https://en.wikipedia.org/wiki/Android_(operating_system)) phones. It is written in C++ and Java, and, while it has an [official autogenerated javascript port](https://github.com/googlei18n/libphonenumber/tree/master/javascript), that port is tightly coupled to Google's `closure` javascript framework, and, when compiled into a [bundle](https://github.com/ruimarinho/google-libphonenumber), 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.
<!-- That's what `libphonenumber-js` is about: I started off from scratch, decyphering Google's code and figuring out how this whole machinery works, through trial and error, with several years of hacking around, receiving bug reports from other developers — eventually, it has reached a state when it can be assumed production-ready. -->
<!--
One part of me was curious about how all this phone number parsing and formatting machinery worked, and another part of me was curious if there was a way to reduce those 530 kilobytes to something more reasonable while also getting rid of all the unnecessary bulk and rewriting it all in pure javascript. The resulting library does everything a modern web application needs while maintaining a much smaller size of about 130 kilobytes.
-->
## 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).
* 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"](https://support.twilio.com/hc/en-us/articles/223182068-What-is-a-short-code-) (short SMS-only numbers), numbers starting with a [`*`](https://github.com/googlei18n/libphonenumber/blob/master/FALSEHOODS.md) (like `*555`), etc. The aim of this library is parsing and formatting people's phone numbers.
* Doesn't provide an equivalent of `formatNumberForMobileDialing()` function that returns a number formatted in such a way that it can be dialed from a mobile phone within a specific country. For example, it adds ["carrier codes"](https://www.bandwidth.com/glossary/carrier-identification-code-cic/) when dialing within certain countries (Brazil, Colombia). Since this is not a dialing library, it doesn't provide such a function and doesn't use "carrier codes" when formatting phone numbers.
<!-- (Australia, Bolivia, Brazil, China, Colombia, Croatia, Faroe Islands, South Korea, Liechtenstein, Luxembourg, Venezuela) -->
<!--
for (var code of Object.keys(metadata.countries)) {
var country = metadata.countries[code]
if (country.formats && country.formats.find(_ => _.domestic_carrier_code_formatting_rule)) {
console.log(code)
}
}
-->
* Doesn't parse alphabetic phone numbers like `1-800-GOT-MILK`: people don't input their phone numbers in this format, it's only used in advertisement.
* Doesn't parse "combined" extensions into two separate numbers (example: `(530) 583-6985 x302/x2303`): people don't input their phone numbers in this format.
* Doesn't use hyphens and brackets when formatting international phone numbers, only whitespace: seems more logical this way.
* Doesn't use the `"001"` country code for ["non-geographic"](#non-geographic) phone numbers. Instead, `PhoneNumber` class has an `.isNonGeographic()` method.
<!--
* Doesn't use ["carrier codes"](https://github.com/googlei18n/libphonenumber/blob/master/FALSEHOODS.md) when formatting numbers: "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.
(`.formatNumberForMobileDialing()` method is not implemented therefore there's no need to format carrier codes)
-->
## GitHub
On March 9th, 2020, GitHub, Inc. silently [banned](https://medium.com/@catamphetamine/how-github-blocked-me-and-all-my-libraries-c32c61f061d3) my account (erasing all my repos, issues and comments) without any notice or explanation. Because of that, all source codes had to be promptly moved to GitLab. The [GitHub repo](https://github.com/catamphetamine/libphonenumber-js) is now only used as a backup (you can star the repo there too), and the primary repo is now the [GitLab one](https://gitlab.com/catamphetamine/libphonenumber-js). Issues can be reported in any repo.
## Install
via [npm](https://npmjs.org/)
```sh
$ npm install libphonenumber-js --save
```
via [yarn](https://yarnpkg.com)
```sh
$ yarn add libphonenumber-js
```
If you're not using a bundler then use a [standalone version from a CDN](https://gitlab.com/catamphetamine/libphonenumber-js/#cdn).
## Use
### Parse phone number
<!--
_(new API)_
-->
```js
import parsePhoneNumber from 'libphonenumber-js'
const phoneNumber = parsePhoneNumber('Phone: 8 (800) 555 35 35.', 'RU')
if (phoneNumber) {
phoneNumber.country === 'RU'
phoneNumber.number === '+78005553535'
phoneNumber.isValid() === true
// Note: `.getType()` requires `/max` metadata: see below for an explanation.
phoneNumber.getType() === 'TOLL_FREE'
}
```
<!--
<details>
<summary>Legacy API</summary>
```js
import { parseNumber } from 'libphonenumber-js'
parseNumber('Phone: 8 (800) 555 35 35.', 'RU')
// Outputs: { country: 'RU', phone: '8005553535' }
```
</details>
-->
### Format phone number
<!--
_(new API)_
-->
```js
import parsePhoneNumber from 'libphonenumber-js'
const phoneNumber = parsePhoneNumber('+12133734253')
phoneNumber.formatInternational() === '+1 213 373 4253'
phoneNumber.formatNational() === '(213) 373-4253'
phoneNumber.getURI() === 'tel:+12133734253'
```
<!--
<details>
<summary>Legacy API</summary>
```js
import { formatNumber } from 'libphonenumber-js'
formatNumber('+12133734253', 'INTERNATIONAL')
// Outputs: '+1 213 373 4253'
formatNumber('+12133734253', 'NATIONAL')
// Outputs: '(213) 373-4253'
formatNumber({ country: 'US', phone: '2133734253' }, 'INTERNATIONAL')
// Outputs: '+1 213 373 4253'
formatNumber({ country: 'US', phone: '2133734253' }, 'NATIONAL')
// Outputs: '(213) 373-4253'
```
</details>
-->
### "As You Type" formatter
```js
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
<!--
_(new API)_
-->
```js
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.full.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()`](#isvalid)) and detecting phone number type (via [`.getType()`](#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](#customizing-metadata) 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
"Country code" means either a [two-letter ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) (like `US`). <!-- or a special `001` country code used for ["non-geographic entities"](#non-geographic) (as per [Google's libphonenumber library](https://github.com/googlei18n/libphonenumber/blob/0068d861a68d3d4612f7bf8646ab844dd3cefce5/java/libphonenumber/test/com/google/i18n/phonenumbers/RegionCode.java#L23-L24)). -->
### Non-geographic
There're several calling codes that don't belong to any country:
* `+800` — [Universal International Toll Free Number](https://en.wikipedia.org/wiki/Toll-free_telephone_number)
* `+808` — [Universal International Shared Cost Number](https://en.wikipedia.org/wiki/Shared-cost_service)
* `+870` — [Inmarsat Global Limited](https://en.wikipedia.org/wiki/Inmarsat)
* `+878` — [Universal Personal Telecommunications](https://en.wikipedia.org/wiki/Universal_Personal_Telecommunications)
* `+881` — [Global Mobile Satellite System](https://en.wikipedia.org/wiki/Global_Mobile_Satellite_System)
* `+882` and `+883` — [International Networks](https://en.wikipedia.org/wiki/International_Networks_(country_code))
* `+888` — [United Nations Office for the Coordination of Humanitarian Affairs](https://en.wikipedia.org/wiki/United_Nations_Office_for_the_Coordination_of_Humanitarian_Affairs#International_Dialing_Code)
* `+979` — [International Premium Rate Service](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/Telephone_numbers_in_France) 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](https://en.wikipedia.org/wiki/North_American_Numbering_Plan) 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`.
Can be imported both as a "default" export and as a "named" export.
```js
import parsePhoneNumberFromString from 'libphonenumber-js'
// Or: 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`](#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](#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"](#non-geographic) 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 `parsePhoneNumberWithError()` function which throws the exact error:
```js
import { parsePhoneNumberWithError, ParseError } from 'libphonenumber-js'
try {
const phoneNumber = parsePhoneNumberWithError('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
}
}
```
<details>
<summary>Possible errors</summary>
* `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).
</details>
### `PhoneNumber`
<!--
`PhoneNumber` class constructor accepts two arguments: `country`/`countryCallingCode` and `nationalNumber`. Also `metadata`.
```js
const phoneNumber = new PhoneNumber('RU', '8005553535', metadata)
```
-->
`PhoneNumber` class instance has the following properties:
* `number: string` — The phone number in [`E.164`](https://en.wikipedia.org/wiki/E.164) format. Example: `"+12133734253"`.
* `countryCallingCode: string` — The [country calling code](#country-calling-code). Example: `"1"`.
* `nationalNumber: string` — The [national (significant) number](#national-significant-number). Example: `"2133734253"`.
* `country: string?` — The [country code](#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](#non-geographic).
* `ext: string?` — The [phone number extension](https://en.wikipedia.org/wiki/Extension_(telephone)), if any. Example: `"1234"`.
* `carrierCode: string?` — The ["carrier code"](https://www.voip-info.org/carrier-identification-codes/), 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 `format`s:
* `NATIONAL` — Example: `"(213) 373-4253"`
* `INTERNATIONAL` — Example: `"+1 213 373 4253"`
* [`E.164`](https://en.wikipedia.org/wiki/E.164) — Example: `"+12133734253"`
* [`RFC3966`](https://www.ietf.org/rfc/rfc3966.txt) (the phone number URI) — Example: `"tel:+12133734253;ext=123"`
* `IDD` — ["Out-of-country" dialing](https://wikitravel.org/en/International_dialling_prefix) format. Example: `"011 7 800 555 35 35"` 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`.
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.
* `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:
```js
import parsePhoneNumber from 'libphonenumber-js'
const phoneNumber = parsePhoneNumber('+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](#min-vs-max-vs-mobile-vs-core) 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.
<details>
<summary>See an example illustrating different results when using <code>/min</code> vs <code>/max</code> vs <code>/mobile</code></summary>
####
```js
import parseMin from 'libphonenumber-js/min'
import parseMax from 'libphonenumber-js/max'
import 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}|[369]|7000|8(?:\d{2})?)\d{7}`.
parseMin('+6589555555').isValid() === true
// The "advanced" validation regexp for mobile numbers is
// `(?:8[1-8]|9[0-8])\\d{6}` and possible lengths are `8`.
parseMax('+6589555555').isValid() === false
parseMobile('+6589555555').isValid() === false
```
</details>
####
See also ["Using phone number validation feature"](#using-phone-number-validation-feature) considerations.
<!--
#### `isValidForRegion(country)`
Is just an alias for `this.isValid() && this.country === country`.
https://github.com/googlei18n/libphonenumber/blob/master/FAQ.md#when-should-i-use-isvalidnumberforregion
-->
#### `getType(): string?`
Returns phone number type (fixed line, mobile, toll free, etc) or `undefined` (if the number is invalid or if there are no phone number type regular expressions for this country in metadata).
By default the library uses "minimal" metadata which is only 75 kilobytes in size but also doesn't include the regular expressions for determining a specific phone number type (fixed line, mobile, toll free, etc) resulting in `getType()` returning `undefined` for most countries. If you don't mind the extra 65 kilobytes of metadata then use ["full" metadata](#min-vs-max-vs-mobile-vs-core) instead (140 kilobytes). Google's library always uses "full" metadata so it will yield different `getNumberType()` results compared to the "minimal" metadata used by default in this library.
<details>
<summary>The list of possible return values</summary>
####
* `MOBILE`
* `FIXED_LINE`
* `FIXED_LINE_OR_MOBILE`
* `PREMIUM_RATE`
* `TOLL_FREE`
* `SHARED_COST`
* `VOIP`
* `PERSONAL_NUMBER`
* `PAGER`
* `UAN`
* `VOICEMAIL`
</details>
####
<details>
<summary>See an example illustrating different results when using <code>/min</code> vs <code>/max</code> vs <code>/mobile</code></summary>
####
```js
import parseMin from 'libphonenumber-js/min'
import parseMax from 'libphonenumber-js/max'
import parseMobile from 'libphonenumber-js/mobile'
// Singapore valid mobile number.
// The (default) "min" bundle doesn't contain any regexps for
// getting phone number type based on national number (for Singapore).
parseMin('+6584655555').getType() === undefined
// The "max" bundle contains regexps for
// getting phone number type based on national number
// for all possible phone number types.
parseMax('+6584655555').getType() === 'MOBILE'
// The "mobile" bundle contains regexps for
// getting phone number type based on national number
// for mobile phone numbers only.
parseMobile('+6584655555').getType() === 'MOBILE'
```
</details>
#### `isNonGeographic(): boolean`
Returns `true` if the number belongs to a ["non-geographic numbering plan"](#non-geographic).
#### `isEqual(phoneNumber: PhoneNumber): boolean`
Compares two `PhoneNumber`s: returns `true` if they're equal, `false` otherwise.
### `class` AsYouType([options or defaultCountry])
Creates a formatter for a partially entered phone number.
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"](#non-geographic) and they don't have a country code, so `defaultCountry` can't be specified for them.
The formatter instance has the following methods:
* `input(text: string)` — Appends text to the input. Returns the formatted phone number.
* `reset()` — Resets the input.
```js
new AsYouType().input('+12133734') === '+1 213 373 4'
new AsYouType('US').input('2133734') === '(213) 373-4'
```
The formatter instance also provides the following getters:
* `getNumber(): PhoneNumber` — Returns the [`PhoneNumber`](#phonenumber). Will return `undefined` if no [national (significant) number](#national-significant-number) digits have been entered so far, or if no `defaultCountry`/`defaultCallingCode` has been set and the user enters a phone number not in international format.
* `getChars(): string` — Returns the phone number characters entered by the user: digits and a `+` sign (if present). Returns an empty string if no phone number characters have been input.
* `getTemplate(): string` — Returns the template used to format the phone number characters (digits and a `+` sign, if present), which are denoted by `x`-es. Returns an empty string if no phone number characters have been input.
```js
// National phone number input example.
const asYouType = new AsYouType('US')
asYouType.input('2') === '2'
asYouType.getNumber().number === '+12'
asYouType.getChars() === '2'
asYouType.getTemplate() === 'x'
asYouType.input('1') === '21'
asYouType.getNumber().number === '+121'
asYouType.getChars() === '21'
asYouType.getTemplate() === 'xx'
asYouType.input('3') === '(213)'
asYouType.getNumber().number === '+1213'
asYouType.getChars() === '213'
asYouType.getTemplate() === '(xxx)'
asYouType.input('3734253') === '(213) 373-4253'
asYouType.getNumber().number === '+12133734253'
asYouType.getChars() === '2133734253'
asYouType.getTemplate() === '(xxx) xxx-xxxx'
// International phone number input example.
const asYouType = new AsYouType()
asYouType.input('+1-213-373-4253') === '+1 213 373 4253'
asYouType.getNumber().country === 'US'
asYouType.getNumber().number === '+12133734253'
asYouType.getChars() === '+12133734253'
asYouType.getTemplate() === 'xx xxx xxx xxxx'
```
* `isInternational(): boolean` — Returns `true` if the phone number is being input in international format. In other words, returns `true` if and only if the parsed phone number starts with a `"+"`.
* `getCallingCode(): string` — Returns the ["country calling code"](#country-calling-code) part of the phone number. Returns `undefined` if the number is not being input in international format. Returns "country calling code" for ["non-geographic"](#non-geographic) phone numbering plans too.
* `getCountry(): string` — Returns a two-letter [country code](#country-code) of the phone number. Returns `undefined` for ["non-geographic"](#non-geographic) phone numbering plans. Returns `undefined` if no phone number has been input yet.
* `isPossible(): boolean` — Returns `true` if the phone number is "possible". Is just a shortcut for [`PhoneNumber.isPossible()`](#ispossible-boolean).
* `isValid(): boolean` — Returns `true` if the phone number is "valid". Is just a shortcut for [`PhoneNumber.isValid()`](#isvalid-boolean).
<details>
<summary>Legacy API (before version <code>1.6.0</code>)</summary>
####
For legacy API (before version `1.6.0`) the formatter instance provides the following getters:
* `country: string?` — Phone number [country](#country-code). Will return `undefined` if the country couldn't be derived from the number.
* `getNationalNumber(): string` — Returns the national (significant) number part of the phone number.
* `getTemplate(): string?` — Same as the current version of `getTemplate()` with the only difference that it returns `undefined` if no suitable format was found for the number being entered (or if no [national (significant) number](#national-significant-number) has been entered so far).
```js
// National phone number input example.
const asYouType = new AsYouType('US')
asYouType.input('2') === '2'
asYouType.getNationalNumber() === '2'
asYouType.input('1') === '21'
asYouType.getNationalNumber() === '21'
asYouType.input('3') === '(213)'
asYouType.getNationalNumber() === '213'
asYouType.input('3734253') === '(213) 373-4253'
asYouType.getNationalNumber() === '2133734253'
// International phone number input example.
const asYouType = new AsYouType()
asYouType.input('+1-213-373-4253') === '+1 213 373 4253'
asYouType.country === 'US'
asYouType.getNationalNumber() === '2133734253'
```
</details>
####
"As You Type" formatter was created by Google as part of their Android OS and therefore only works for numerical keyboard input, i.e. it can only accept digits (and a `+` sign in the start of an international number). When used on desktops where a user can input all kinds of punctuation (spaces, dashes, parens, etc) it simply ignores everything except digits (and a `+` sign in the start of an international number).
Google's "As You Type" formatter does not support entering phone number extensions. If your project requires phone number extensions input then use a separate input field for that.
### findPhoneNumbersInText(text: string, [defaultCountry: string?], [options]): object[]
Searches for phone numbers in `text`.
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"](#non-geographic) and they don't have a country code, so `defaultCountry` can't be specified for them.
```js
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
// }]
```
(in previous versions, it was called `findNumbers()`)
<details>
<summary>Legacy API (before version <code>1.6.0</code>) example</summary>
####
```js
import { findNumbers } from 'libphonenumber-js'
findNumbers(`
For tech support call +7 (800) 555-35-35 internationally
or reach a local US branch at (213) 373-4253 ext. 1234.
`, 'US')
// Outputs:
//
// [{
// phone : '8005553535',
// country : 'RU',
// startsAt : 22,
// endsAt : 40
// },
// {
// phone : '2133734253',
// country : 'US',
// ext : '1234',
// startsAt : 86,
// endsAt : 110
// }]
```
</details>
####
By default it processes the whole text and then outputs the phone numbers found. If the text is very big (say, a hundred thousand characters) then it might freeze the user interface for a couple of seconds. To avoid such lags one can employ "iterator" approach using `searchPhoneNumbersInText()` to perform the search asynchronously (e.g. using `requestIdleCallback` or `requestAnimationFrame`).
(in previous versions, it was called `searchNumbers()`)
<details>
<summary>Asynchronous search example using <code>searchPhoneNumbersInText()</code></summary>
####
ES6 iterator:
```js
import { searchPhoneNumbersInText } from 'libphonenumber-js'
const text = `
For tech support call +7 (800) 555-35-35 internationally
or reach a local US branch at (213) 373-4253 ext. 1234.
`
async function() {
for (const number of searchPhoneNumbersInText(text, 'US')) {
console.log(number)
await new Promise(resolve => setTimeout(resolve, 0))
}
console.log('Finished')
}
```
Java-style iterator (for those still not using ES6):
```js
import { PhoneNumberMatcher } from 'libphonenumber-js'
const matcher = new PhoneNumberMatcher(`
For tech support call +7 (800) 555-35-35 internationally
or reach a local US branch at (213) 373-4253 ext. 1234.
`, {
defaultCountry: 'US',
v2: true
})
// Search cycle iteration.
const iteration = () => {
if (matcher.hasNext()) {
console.log(matcher.next())
setTimeout(iteration, 0)
} else {
console.log('Finished')
}
}
// Run the search.
iteration()
```
</details>
####
Although Google's javascript port doesn't have the `findPhoneNumbersInText()` functionality the Java and C++ ports do. I guess Google just doesn't need to crawl phone numbers on Node.js because they can afford to hire a Java/C++ developer to do that. Still, javascript nowadays is the most popular programming language given its simplicity and user-friendliness. The `findPhoneNumbersInText()` function provided is a port of Google's `PhoneNumberMatcher.java` into javascript.
### getExampleNumber(country: string, examples: object): PhoneNumber
Returns an example phone number for a [country](#country-code). Returns an instance of [`PhoneNumber`](#phonenumber) class. Will return `undefined` if `country` doesn't exist or isn't supported by this library.
```js
import examples from 'libphonenumber-js/examples.mobile.json'
import { getExampleNumber } from 'libphonenumber-js'
const phoneNumber = getExampleNumber('RU', examples)
phoneNumber.formatNational() === '8 (912) 345-67-89'
```
### isSupportedCountry(country: string): boolean
Checks if a country is supported by this library.
```js
isSupportedCountry('RU') === true
isSupportedCountry('XX') === false
```
### getCountries(): string[]
Returns a list of supported countries.
<!-- (excluding `"001"` that stands for ["non-geographic entity"](#non-geographic)). -->
```js
getCountries() === ["AC", "AD", ...]
```
### getCountryCallingCode(country: string): string
Returns [country calling code](#country-calling-code) for a [country](#country-code). Will throw an error if `country` doesn't exist or isn't supported by this library.
```js
getCountryCallingCode('RU') === '7'
getCountryCallingCode('IL') === '972'
```
### getExtPrefix(country: string): string
Returns phone number extension prefix for a given `country`. If no custom ext prefix is defined for a `country` then the default `" ext. "` prefix is returned.
```js
getExtPrefix('US') === ' ext. '
getExtPrefix('GB') === ' x'
```
<!--
### parsePhoneNumberCharacter(nextCharacter, prevParsedCharacters)
Parses next character while parsing phone number digits (including a `+`) from text: discards everything except `+` and digits, and `+` is only allowed at the start of a phone number.
For example, is used in [`input-format`](https://gitlab.com/catamphetamine/input-format).
```js
// Suppose a user inputs "+1 (213) 373-42-53".
parsePhoneNumberCharacter('+', undefined) === '+'
parsePhoneNumberCharacter('1', '+') === '1'
parsePhoneNumberCharacter(' ', '+1') === undefined
parsePhoneNumberCharacter('(', '+1') === undefined
parsePhoneNumberCharacter('2', '+1') === '2'
parsePhoneNumberCharacter('1', '+12') === '1'
parsePhoneNumberCharacter('3', '+121') === '3'
parsePhoneNumberCharacter(')', '+1213') === undefined
parsePhoneNumberCharacter(' ', '+1213') === undefined
parsePhoneNumberCharacter('3', '+1213') === '3'
parsePhoneNumberCharacter('7', '+12133') === '7'
parsePhoneNumberCharacter('3', '+121337') === '3'
parsePhoneNumberCharacter('-', '+121337') === undefined
parsePhoneNumberCharacter('4', '+1213373') === '4'
parsePhoneNumberCharacter('2', '+12133734') === '2'
parsePhoneNumberCharacter('-', '+12133734') === undefined
parsePhoneNumberCharacter('5', '+121337342') === '5'
parsePhoneNumberCharacter('3', '+1213373425') === '3'
```
-->
### parseDigits(text: string): string
Parses digits from string. Can be used for building a phone number extension input component (e.g. [react-phone-number-input](https://gitlab.com/catamphetamine/react-phone-number-input/)).
```js
parseDigits('x123') === '123'
parseDigits('٤٤٢٣') === '4423'
```
### parseIncompletePhoneNumber(text: string): string
Parses phone number characters (`+` and digits). Can be used for building a phone number input component (e.g. [react-phone-number-input](https://gitlab.com/catamphetamine/react-phone-number-input/)).
```js
parseIncompletePhoneNumber('8 (800) 555') === '8800555'
parseIncompletePhoneNumber('+7 800 555') === '+7800555'
parseIncompletePhoneNumber('+٤٤٢٣٢٣٢٣٤') === '+442323234'
```
### formatIncompletePhoneNumber(value: string, country: string?): string
Formats incomplete phone number as a national one for a given `country`. If `country` is not specified then outputs the phone number in international format. This is just an alias for `new AsYouType(country, metadata).input(value)`. Can be used for building a phone number input component (e.g. [react-phone-number-input](https://gitlab.com/catamphetamine/react-phone-number-input/)).
```js
formatIncompletePhoneNumber('8800555', 'RU') === '8 (800) 555'
formatIncompletePhoneNumber('+7800555') === '+7 800 555'
```
## Legacy API
<details>
<summary>Legacy API (before version <code>1.6.0</code>): <code>parse()</code>, <code>parseNumber()</code>, <code>format()</code>, <code>formatNumber()</code>, <code>isValidNumber()</code>, <code>getNumberType()</code>.</summary>
### parseNumber(text, [defaultCountry], [options])
_(previously called `parse()`)_
_(legacy API)_
Attempts to parse a phone number from `text`.
If [`defaultCountry`](#country-code) is passed then it's gonna be the default country for parsing non-international phone numbers.
Returns `{ country, phone, ext }` object where
* `country` is a [country code](#country-code).
* `phone` is a [national (significant) number](#national-significant-number).
* `ext` is a [phone number extension](https://en.wikipedia.org/wiki/Extension_(telephone)).
If the phone number supplied isn't valid then an empty object `{}` is returned.
<details>
<summary>Examples</summary>
```js
// Parses international numbers.
parseNumber('+1 213 373 4253') === { country: 'US', phone: '2133734253' }
parseNumber('Phone: +1-213-373-4253.') === { country: 'US', phone: '2133734253' }
parseNumber('+12133734253') === { country: 'US', phone: '2133734253' }
// Parses national numbers provided a default country.
parseNumber('Phone: (213) 373-4253.', 'US') === { country: 'US', phone: '2133734253' }
// Parses phone number extensions.
parseNumber('(213) 373-4253 ext. 123', 'US') === { country: 'US', phone: '2133734253', ext: '123' }
// Parses RFC 3966 phone number URIs.
parseNumber('tel:+78005553535;ext=123') === { country: 'RU', phone: '8005553535', ext: '123' }
```
If the phone number supplied isn't valid then an empty object `{}` is returned.
```js
parseNumber('+1 111 111 1111') === {}
parseNumber('(111) 111-1111', 'US') === {}
parseNumber('abcdefg') === {}
```
</details>
####
Available `options`:
* `defaultCountry : string` — Same as the `defaultCountry` argument.
* `extended : boolean` — If set to `true` then `parseNumber()` will attempt to parse even a remotely hypothetical phone number even if it is considered "invalid".
<details>
<summary><code>{ extended: true }</code> documentation and examples</summary>
The result of "extended" parsing is an object where
* `country` is a [country code](#country-code).
* `phone` is a [national (significant) number](#national-significant-number).
* `ext` is a [phone number extension](https://en.wikipedia.org/wiki/Extension_(telephone)).
* `countryCallingCode` is a [country calling code](#country-calling-code).
* [`carrierCode`](https://www.voip-info.org/carrier-identification-codes/)s are only used in Colombia and Brazil and only when dialing within those countries from a mobile phone to a fixed line number.
* `valid: boolean` — whether it's a "valid" (real) phone number.
* `possible: boolean` — a phone number is considered "possible" when it fits the phone number length rules for a given country. E.g. for US national (significant) number regexp is `[2-9]\d{9}` and possible national (significant) number length is `10` so a phone number `(111) 111-1111` is not a "valid" number because it doesn't match the US national (significant) number regexp but it is a "possible" number because it's `10` digits long.
* Some or all of these properties may be absent from the result object.
```js
// If the number is valid.
parseNumber('Phone: (213) 373-4253.', 'US', { extended: true }) ===
{
country: 'US',
phone: '2133734253',
ext: undefined,
countryCallingCode: 1,
carrierCode: undefined,
valid: true,
possible: true
}
// If the number is not "valid" but "possible".
parseNumber('(111) 111-1111', 'US', { extended: true }) ===
{
country: 'US',
phone: '1111111111',
ext: undefined,
countryCallingCode: 1,
carrierCode: undefined,
valid: false,
possible: true
}
// If the number is not "valid" but "possible"
// and country can't be derived from it.
// (e.g. can't tell if it's a US number or a Canadian number)
parseNumber('+1 111 111 1111', { extended: true }) ===
{
country: undefined,
phone: '1111111111',
ext: undefined,
countryCallingCode: 1,
carrierCode: undefined,
valid: false,
possible: true
}
// If the number is not "possible" (invalid length).
parseNumber('(213) 373', 'US', { extended: true }) ===
{
country: 'US',
phone: '213373',
ext: undefined,
countryCallingCode: 1,
carrierCode: undefined,
valid: false,
possible: false
}
// In some cases if the number is extremely not "possible"
// then an empty object `{}` is returned.
//
// Too short (or too long) for any country's phone number.
parseNumber('1', 'US', { extended: true }) === {}
// Non-existent country calling code.
parseNumber('+210', { extended: true }) === {}
// No phone number found.
parseNumber('abcdefg', 'US', { extended: true }) === {}
```
The "extended" parsing mode is the default behaviour of the original Google's `libphonenumber`: it still returns parsed data even if the phone number being parsed is not considered valid (but is kinda "possible"). I guess this kind of behaviour is better for crawling websites for phone numbers because when mining "big data" it is better to extract all possible info rather than discard some pieces of it prematurely, e.g. when national (significant) number regexp for some country gets outdated which might very well happen because phone numbering plans are changing constantly around the world. Maybe after all it would make sense to make the "extended" parsing mode the default one in the next major version. I guess it would.
</details>
####
<details>
<summary>Also parses IDD-prefixed phone numbers</summary>
Sometimes users icorrectly input phone numbers in ["out-of-country" dialing](https://wikitravel.org/en/International_dialling_prefix) (IDD-prefixed) format instead of the proper international phone number format (the "+" notation). In such cases `parseNumber()` will attempt to parse such IDD-prefixed numbers if "default country" is provided:
```js
// International format.
parseNumber('+61 2 3456 7890') === { country: 'AU', phone: '234567890' }
// IDD-prefixed format.
parseNumber('011 61 2 3456 7890', 'US') === { country: 'AU', phone: '234567890' }
```
</details>
### formatNumber(number, format, [options])
_(previously called `format()`)_
_(legacy API)_
Formats a `number` into a string according to a `format`.
Available `format`s and `options` are the same as for [`PhoneNumber.format(format)`](#formatformat-string-options).
The `number` argument must be either a result of `parseNumber()` function call (to strip national prefix) or an E.164 phone number string (e.g. `+12133734253`).
<details>
<summary>Examples</summary>
```js
// Formats E.164 phone numbers.
formatNumber('+12133734253', 'NATIONAL') === '(213) 373-4253'
formatNumber('+12133734253', 'INTERNATIONAL') === '+1 213 373 4253'
// Formats E.164 phone numbers when
// they're not "valid" but still "possible".
formatNumber('+11111111111', 'NATIONAL') === '(111) 111-1111'
formatNumber('+11111111111', 'INTERNATIONAL') === '+1 111 111 1111'
// Formats E.164 phone numbers when
// they're not "valid" and not "possible" (invalid length).
formatNumber('+11111', 'NATIONAL') === '1111'
formatNumber('+11111', 'INTERNATIONAL') === '+1 1111'
// Formats a result of `parseNumber()` function call.
const parsedNumber = parseNumber('2133734253', 'US')
formatNumber(parsedNumber, 'NATIONAL') === '(213) 373-4253'
formatNumber(parsedNumber, 'INTERNATIONAL') === '+1 213 373 4253'
// Formats a result of `parseNumber()` function call in "extended" mode
// when it's not a "valid" number but is still a "possible" one.
const possibleNumber = parseNumber('+11111111111', { extended: true })
formatNumber(possibleNumber, 'NATIONAL') === '(111) 111-1111'
formatNumber(possibleNumber, 'INTERNATIONAL') === '+1 111 111 1111'
// Formats a result of `parseNumber()` function call in "extended" mode
// when it's neither a "valid" number nor a "possible" one (invalid length).
const possibleNumber = parseNumber('+11111', { extended: true })
formatNumber(possibleNumber, 'NATIONAL') === '1111'
formatNumber(possibleNumber, 'INTERNATIONAL') === '+1 1111'
// Formats phone number extensions.
formatNumber({ country: 'US', phone: '2133734253', ext: '123' }, 'NATIONAL') === '(213) 373-4253 ext. 123'
// When given an object not having `phone` property
// (e.g. a empty object `{}`) it will throw.
formatNumber({}) throws Error
```
</details>
### getNumberType(number, [defaultCountry])
_(legacy API)_
See the description for [`PhoneNumber.getType()`](#gettype).
The `number` argument can be either a result of the `parseNumber()` function call — `{ country, phone }` — or a string (phone number digits only) possibly accompanied with the second `defaultCountry` argument.
<details>
<summary>Examples</summary>
```js
getNumberType('+79160151539') === 'MOBILE'
getNumberType('9160151539', 'RU') === 'MOBILE'
getNumberType({ phone: '9160151539', country: 'RU' }) === 'MOBILE'
```
</details>
### isValidNumber(number, [defaultCountry])
_(legacy API)_
Checks if a phone number is valid, the validation is more strict than `parseNumber()`.
The `number` argument can be either a result of the `parseNumber()` function call — `{ country, phone }` — or a string (phone number digits only) possibly accompanied with the second `defaultCountry` argument.
<details>
<summary>Examples</summary>
```js
isValidNumber('+12133734253') === true
isValidNumber('+1213373') === false
isValidNumber('2133734253', 'US') === true
isValidNumber('21337', 'US') === false
isValidNumber({ phone: '2133734253', country: 'US' }) === true
```
</details>
####
<details>
<summary>The difference between using <code>parseNumber()</code> and <code>isValidNumber()</code></summary>
The difference between using `parseNumber()` and `isValidNumber()` for phone number validation is that `isValidNumber()` also checks the precise regular expressions of possible phone numbers for a country. For example, for Germany `parseNumber('123456', 'DE')` would return `{ country: 'DE', phone: '123456' }` because this phone number matches the general phone number rules for Germany (basic length check, etc). But, if the metadata is compiled with `--extended` (or relevant `--types`) flag (see [Customizing metadata](#customizing-metadata) section of this document) then `isValidNumber()` is gonna use those precise regular expressions for extensive validation and `isValid('123456', 'DE')` will return `false` because the phone number `123456` doesn't actually exist in Germany.
This is how it is implemented in the original Google's [`libphonenumber`](https://static.javadoc.io/com.googlecode.libphonenumber/libphonenumber/8.9.1/com/google/i18n/phonenumbers/PhoneNumberUtil.html#parse-java.lang.CharSequence-java.lang.String-): `parseNumber()` parses phone numbers and loosely validates them while `isValidNumber()` validates phone numbers precisely (provided the precise regular expressions are included in metadata).
The precise regular expressions aren't included in the default metadata because that would cause the default metadata to grow twice in its size: the complete ("full") metadata size is about 145 kilobytes while the reduced ("default") metadata size is about 77 kilobytes. Hence in the default configuration `isValidNumber()` performs absolutely the same "lite" validation as `parseNumber()`. For enabling extensive phone number validation the simplest way is to import functions from `libphonenumber-js/custom`