repository·master·Indexed 25 days ago
https://github.com/catamphetamine/libphonenumber-jsA lightweight, high-performance JavaScript/TypeScript rewrite of Google's libphonenumber library. It provides phone number parsing, formatting, and validation with configurable metadata density (min, max, mobile, or custom) to optimize bundle size. Key features include the AsYouType formatter, phone number extraction from text, and support for both official ISO 3166-1 alpha-2 and unofficial country codes.
A Country calling code refers to the digits located between the + symbol and the national (significant) number in an international format number.
+1 213 373 4253, the country calling code is 1.+33 1 45 45 32 45, the country calling code is 33.Note that multiple countries may share the same country calling code (e.g., USA, Canada, and several Caribbean nations all use 1).
A National (significant) number consists of all digits in a national phone number excluding the "national prefix".
+1 213 373 4253, the national number is (213) 373-4253 and the national (significant) number is 213 373 4253.+33 1 45 45 32 45, the national number is 01 45 45 32 45. The national (significant) number is 1 45 45 32 45 (the leading 0 is removed as it is the national prefix).metadata.json file (generated from Google's PhoneNumberMetadata.xml) as the source of truth for phone number rules. While metadata.json itself is an intermediary file and not included in the final distribution, the library provides optimized versions like metadata.min.json. The metadata contains information regarding country calling codes, national prefixes, and number patterns.You can include the library directly in a web page using a <script> tag from a CDN like unpkg.com or jsdeliv.com. You must specify the version and the bundle type (min, max, or mobile).
<script src="https://unpkg.com/libphonenumber-js@[version]/bundle/libphonenumber-[type].js"></script>
<script>
alert(new libphonenumber.AsYouType('US').input('213-373-4253'))
</script>libphonenumber-js/core. The functions in this sub-package do not come with pre-packaged metadata; instead, they accept metadata as the last argument of each exported function.To optimize bundle size, libphonenumber-js provides different metadata sets. Choose the one that matches your validation and feature requirements:
min (Default): Smallest size (~80kB). Use when you only need basic length validation via .isPossible() and do not need to detect phone number types (e.g., via .getType()) or perform strict digit validation via .isValid().max: Complete metadata (~145kB). Use when you need strict digit validation via .isValid() and phone number type detection via .getType().mobile: Mobile-focused metadata (~95kB). Use when you need max capabilities but only intend to support mobile numbers. Note that non-mobile numbers might return false for .isValid() or undefined for .getType().custom (Advanced): Use when you only need to support a specific subset of countries and want to minimize bundle size by generating your own metadata.The library is written in ES6 and uses Babel for ES5 transpilation. Run the build script to generate the distribution files.
npm run buildAfter making changes, run the test suite. To ensure quality, check that the code coverage (statements percentage) remains at 100% using the coverage script.
npm test
npm run test-coverageTo contribute to the library, clone the repository and install the necessary dependencies using npm.
npm installWhen validating phone numbers, you can choose between two methods:
.isPossible(): Validates only the length of the phone number. This is recommended for business requirements to avoid issues where telephone numbering plans change and the library becomes outdated. It is more resilient for long-term maintenance..isValid(): Validates both the length and the actual digits. Use this if you require strict validation, but be aware that you must keep the library updated to reflect changes in global numbering plans.Instead of importing from the main package, import from the sub-package corresponding to the metadata set you want to use to control bundle size:
| Metadata Set | Import Path |
|---|---|
min | libphonenumber-js/min (or libphonenumber-js) |
max | libphonenumber-js/max |
mobile | libphonenumber-js/mobile |
custom | libphonenumber-js/core |
If you only need to support ES6-compliant browsers, append /es6 to the path (e.g., libphonenumber-js/max/es6).
Install the library using npm to add it to your project dependencies.
npm install libphonenumber-js --save