The Fastest Phone Number Library

Parse, validate, and format phone numbers with blazing speed and tiny bundles. TypeScript-first, up to 11x faster than alternatives.

Get Started API Documentation

Why ts-phonenumber?

Built for performance without compromising on features

Blazing Fast

Pre-compiled RegExp patterns and bitmap-based validation. Up to 11x faster than google-libphonenumber.

Tiny Bundles

~5KB core + on-demand metadata loading. Only load the countries you need via dynamic imports.

TypeScript-First

Built from the ground up in TypeScript with full type safety and comprehensive type definitions.

Dual API

Async API for lazy loading in web apps. Sync API for maximum performance in servers and CLIs.

Modern Runtimes

Supports Node.js 20+, Bun, Deno, and modern browsers. ESM and CommonJS builds included.

CLI Included

Command-line tool for quick validation, parsing, and formatting. Great for scripting and debugging.

Installation

Get started with your favorite package manager

npm install ts-phonenumber

pnpm add ts-phonenumber

yarn add ts-phonenumber

bun add ts-phonenumber

Quick Start

Parse, validate, and format phone numbers in seconds

                
                
                
              
TypeScript

              import { parse, validate, format } from "ts-phonenumber"

// Parse a phone number (metadata loaded automatically)
const parsed = await parse("+491701234567")
console.log(parsed.regionCode)  // "DE"
console.log(parsed.type)        // "mobile"

// Validate a phone number
const result = await validate("+491701234567")
console.log(result.isValid)     // true

// Format a phone number
const intl = await format("+491701234567", "international")
console.log(intl)  // "+49 170 1234567"
            

              import { parseSync, validateSync, formatSync, registerMetadata } from "ts-phonenumber"
import DE from "ts-phonenumber/metadata/countries/DE"

// Pre-load metadata once at startup
registerMetadata(DE)

// Now use sync functions - no async overhead!
const parsed = parseSync("+491701234567")
console.log(parsed.regionCode)  // "DE"
console.log(parsed.type)        // "mobile"

const isValid = validateSync("+491701234567")
console.log(isValid.isValid)    // true

const formatted = formatSync(parsed, "international")
console.log(formatted)  // "+49 170 1234567"
            

              # Install globally or use npx
npm install -g ts-phonenumber

# Validate a phone number
ts-phonenumber validate "+491701234567"
# Output: Valid: mobile

# Parse and show details
ts-phonenumber parse "+491701234567" --json

# Format a number
ts-phonenumber format "+491701234567" --format international
# Output: +49 170 1234567

# Get number type
ts-phonenumber type "+491701234567"
# Output: mobile
            

Performance Benchmarks

ts-phonenumber wins all 7 benchmarks against popular alternatives

Benchmark	ts-phonenumber	vs libphonenumber-js	vs google-libphonenumber
Parse E.164	1.56M/s	3.3x faster	4.9x faster
Parse national	2.14M/s	6.4x faster	9.9x faster
Validate	1.53M/s	5.4x faster	6.2x faster
Format E.164	32.4M/s	4.3x faster	1.5x faster
Format International	2.30M/s	7.3x faster	6.1x faster
Full pipeline	1.51M/s	4.8x faster	11.2x faster
Batch (10 nums)	160K/s	7.4x faster	5.7x faster