{"id":11237,"library":"libphonenumber-js","title":"libphonenumber-js","description":"libphonenumber-js is a JavaScript and TypeScript library designed for parsing, formatting, and validating international phone numbers. It serves as a significantly smaller and simpler rewrite of Google's original `libphonenumber` library. Currently at version 1.12.41, this package prioritizes a reduced bundle size (approximately 145 kB vs. 550 kB for the Google port) by focusing solely on personal phone numbers. It deliberately omits support for less common categories such as emergency numbers, short codes, numbers prefixed with `*`, Australian `13`-smart numbers, and alphabetic phone numbers like `1-800-GOT-MILK`. The library ships with comprehensive TypeScript definitions and uniquely offers functionality to search for phone numbers within text, a feature absent in Google's official JavaScript port. While a specific release cadence isn't detailed, the version history suggests active and ongoing development.","status":"active","version":"1.12.41","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","telephone","phone","number","input","mobile","libphonenumber","typescript"],"install":[{"cmd":"npm install libphonenumber-js","lang":"bash","label":"npm"},{"cmd":"yarn add libphonenumber-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add libphonenumber-js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For parsing a phone number string into a PhoneNumber object. ESM is the primary import style. For CommonJS, use `require('libphonenumber-js').parsePhoneNumber`.","wrong":"const parsePhoneNumber = require('libphonenumber-js');","symbol":"parsePhoneNumber","correct":"import { parsePhoneNumber } from 'libphonenumber-js';"},{"note":"Use named import for `formatPhoneNumber`. There's also `formatPhoneNumberIntl` for international formatting with a leading `+`.","wrong":"import formatPhoneNumber from 'libphonenumber-js/formatPhoneNumber';","symbol":"formatPhoneNumber","correct":"import { formatPhoneNumber } from 'libphonenumber-js';"},{"note":"Checks if a phone number string is valid for a given country. This is a common utility function.","wrong":"import { validatePhoneNumber } from 'libphonenumber-js';","symbol":"isValidPhoneNumber","correct":"import { isValidPhoneNumber } from 'libphonenumber-js';"},{"note":"Retrieves the international calling code for a specified country code (e.g., 'US' -> '1').","wrong":"import { getCallingCode } from 'libphonenumber-js';","symbol":"getCountryCallingCode","correct":"import { getCountryCallingCode } from 'libphonenumber-js';"}],"quickstart":{"code":"import { parsePhoneNumber, formatPhoneNumber, isValidPhoneNumber, getCountryCallingCode } from 'libphonenumber-js';\n\nconst phoneNumberString = '+12133734253';\nconst countryCode = 'US';\n\n// Parse a phone number\nconst phoneNumber = parsePhoneNumber(phoneNumberString);\n\nif (phoneNumber) {\n  console.log(`Original number: ${phoneNumberString}`);\n  console.log(`Country: ${phoneNumber.country}`);\n  console.log(`National number: ${phoneNumber.nationalNumber}`);\n\n  // Format the number in various ways\n  console.log(`Formatted E.164: ${phoneNumber.format('E.164')}`);\n  console.log(`Formatted International: ${phoneNumber.format('INTERNATIONAL')}`);\n  console.log(`Formatted National: ${phoneNumber.format('NATIONAL')}`);\n\n  // Check validity\n  const valid = isValidPhoneNumber(phoneNumberString, countryCode);\n  console.log(`Is valid for ${countryCode}? ${valid}`);\n\n  // Get country calling code\n  const callingCode = getCountryCallingCode(countryCode);\n  console.log(`Calling code for ${countryCode}: +${callingCode}`);\n\n} else {\n  console.log(`Could not parse phone number: ${phoneNumberString}`);\n}\n\n// Example of an invalid number\nconst invalidNumber = '555-123-INVALID';\nconst isValid = isValidPhoneNumber(invalidNumber, countryCode);\nconsole.log(`Is '${invalidNumber}' valid for ${countryCode}? ${isValid}`);","lang":"typescript","description":"Demonstrates parsing, formatting, and validating phone numbers, including checking country-specific validity and retrieving calling codes."},"warnings":[{"fix":"Review your requirements; if special number types are critical, consider using the official (larger) Google `libphonenumber` JavaScript port or a different library that specifically supports them.","message":"libphonenumber-js deliberately omits support for several 'special' phone number categories, including emergency numbers (e.g., 911), short codes, numbers starting with `*`, Australian `13`-smart numbers, and alphabetic numbers (e.g., 1-800-GOT-MILK). It focuses exclusively on personal phone numbers to achieve a smaller bundle size. If your application requires handling these specific types, this library might not be suitable, and you may need Google's full `libphonenumber` port.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Wrap calls to `parsePhoneNumber` in a conditional check: `const phoneNumber = parsePhoneNumber(number); if (phoneNumber) { /* use phoneNumber */ }`.","message":"The `parsePhoneNumber` function returns `undefined` if the input string cannot be parsed into a valid `PhoneNumber` object. Always check the return value before attempting to access properties like `country`, `nationalNumber`, or `format()`, otherwise, it may lead to runtime errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult the `libphonenumber-js` documentation or TypeScript types for the exact accepted format strings for `phoneNumber.format()`.","message":"When formatting numbers, ensure you provide a valid format string (e.g., 'E.164', 'INTERNATIONAL', 'NATIONAL'). Using an unsupported format string will result in an error or unexpected output. Refer to the documentation for supported formats.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Always check if the result of `parsePhoneNumber(string)` is not `undefined` before attempting to access its properties. For example: `const num = parsePhoneNumber(str); if (num) { console.log(num.country); }`.","cause":"`parsePhoneNumber` returned `undefined` because the input string was not a valid or recognizable phone number.","error":"TypeError: Cannot read properties of undefined (reading 'country')"},{"fix":"Ensure `libphonenumber-js` is installed (`npm install libphonenumber-js`) and that your `tsconfig.json` includes `node_modules/@types` or has `\"moduleResolution\": \"node\"` set correctly.","cause":"TypeScript compiler cannot locate the package or its declaration files (`.d.ts`).","error":"TS2307: Cannot find module 'libphonenumber-js' or its corresponding type declarations."},{"fix":"Use ESM `import` statements instead: `import { parsePhoneNumber } from 'libphonenumber-js';`. If using CommonJS, ensure your file is a `.js` file or configured as such, and `require()` is appropriate for your environment.","cause":"Attempting to use `require()` in an ES Module context (e.g., a modern Node.js project or browser module) without proper transpilation or configuration.","error":"ReferenceError: require is not defined"}],"ecosystem":"npm"}