How to install libphonenumber-js

libphonenumber-js is a JavaScript library for parsing, formatting and validating phone numbers. It is a smaller rewrite of Google's libphonenumber that works in browsers and Node.js. This guide covers every way to install it and how to pick the right metadata build.

Install with npm or yarn

Use your package manager. The package ships its own TypeScript types, so you do not need a separate @types package.

npm install libphonenumber-js
# or
yarn add libphonenumber-js
# or
pnpm add libphonenumber-js

Import it

The default build is the lightest one, called "min". Import the functions you need by name. Bundlers can then drop everything else.

import { parsePhoneNumberFromString } from 'libphonenumber-js'

const phone = parsePhoneNumberFromString('+44 20 7946 0958')
phone.isValid()       // true
phone.format('E.164') // '+442079460958'

Pick a metadata build: min, max or mobile

The library needs data about every country's numbering plan. You choose how much of it to ship by changing the import path. The sizes below are the complete browser bundles (code plus data) of version 1.13.15, which we measured ourselves from the npm package.

• min is the default. Choose it when you do not need number types and a length check is enough, which covers most signup forms.
• Switch to max when you need getType() for every country, or the strictest isValid().
• Use mobile when you only accept mobile numbers and want to save bytes.

What min does not check

The min build keeps only the basic rules. The library's documentation says that with min, isValid() behaves the same as isPossible(): it checks the length of a number, but for most countries it does not check the digits against the exact assigned ranges. The same number can therefore be valid in min and invalid in max. We ran both builds on the same input to show it.

import parseMin from 'libphonenumber-js/min'
import parseMax from 'libphonenumber-js/max'

// India: 10 digits starting with 1 is not an assigned range
parseMin('+91 1000000000').isValid() // true  (length fits)
parseMax('+91 1000000000').isValid() // false (digits not in a real range)

// Germany: a real mobile number
parseMin('+49 151 23456789').getType() // undefined: min has no type data here
parseMax('+49 151 23456789').getType() // 'MOBILE'

Use it from a CDN without a build step

For a plain HTML page, load the standalone bundle. It exposes a global named libphonenumber.

<script src="https://unpkg.com/libphonenumber-js@1.13.15/bundle/libphonenumber-max.js"></script>
<script>
  const phone = libphonenumber.parsePhoneNumberFromString('+442079460958')
  console.log(phone.country) // "GB"
</script>

Use it in Node.js

It works in both ES modules and CommonJS. With CommonJS use require.

const { parsePhoneNumberFromString } = require('libphonenumber-js')
console.log(parsePhoneNumberFromString('(415) 555-2671', 'US').number)
// +14155552671

Try it before you install

The playground on this site runs the max build in your browser. Type a number and see the exact object the library returns, with the code that produces it.