license:mit Netlify Status Npm Version Build Status

Phone Fns

A small, modern, and functional phone number library which gathers inspiration from the fun date-fns library

How-To

npm i phone-fns

Standard module system

import * as phoneFns from 'phone-fns'

phoneFns.uglify('555-444-3333') // => '5554443333'

Common JS

const phoneFns = require('phone-fns')

phoneFns.uglify('555-444-3333') // => '5554443333'

Using Unpkg or jsdelivr CDN (As of v4.0.0+)

<script src="https://cdn.jsdelivr.net/npm/phone-fns@5.0.0/dist/phone-fns.iife.min.js"></script>
<script>
  phoneFns.uglify('555-444-3333') // => '5554443333'
</script>

Through the browser

<script src="path/to/location/dist/phone-fns.iife.min.js"></script>
<script>
  phoneFns.uglify('555-444-3333') // => '5554443333'
</script>

TypeScript

Type definitions ship with the package. They work with both import and require, and the Breakdown type can be imported for your own code:

import { breakdown, type Breakdown } from 'phone-fns'

const parts: Breakdown = breakdown('555-444-3333')

Usage

import * as phoneFns from 'phone-fns'

phoneFns.breakdown('4443332222')
// => { countryCode: '', areaCode: '444', localCode: '333', lineNumber: '2222', extension: '' }

phoneFns.format('(NNN) NNN-NNNN', '4443332222')
// => '(444) 333-2222'

You can also destructure to only use the functions you want

import { breakdown, format } from 'phone-fns'

breakdown('4443332222')
// => { countryCode: '', areaCode: '444', localCode: '333', lineNumber: '2222', extension: '' }

format('(NNN) NNN-NNNN', '4443332222')
// => '(444) 333-2222'

Validation

validate checks that a phone number is written sensibly, without applying any country specific numbering rules. This lets it work with phone numbers from anywhere:

  • It may start with a + and a country code
  • Digits are grouped with a single space, dot, or dash, and one group can be wrapped in parentheses
  • It has 10 to 15 digits, country code included
  • Extensions are marked with x, ext, ext., extension, or #
import { validate } from 'phone-fns'

validate('555-444-3333') // => true
validate('+44 (0)20 7946 0958') // => true
validate('555--444-3333') // => false

Because it doesn't know each country's rules, a number can pass validate without being a real, dialable number. If you need that level of accuracy (or want to know whether a number is a mobile or landline), use libphonenumber-js, which ships the full metadata for every country. Phone-Fns stays small by leaving that metadata out.

If you know the exact layout you expect, isValidWithFormat checks a number against it:

import { isValidWithFormat } from 'phone-fns'

isValidWithFormat('NNN-NNN-NNNN', '555-444-3333') // => true
isValidWithFormat('NNN-NNN-NNNN', '555.444.3333') // => false

Placeholder Support

Phone-Fns as of v3.2.0 now supports placeholder syntax using Underscores _

const fn = format('NNN-NNN-NNNN')

fn('__________') // => '___-___-____'
fn('444_______') // => '444-___-____'
fn('444555____') // => '444-555-____'
fn('4445556666') // => '444-555-6666'
format('NNN-NNN-NNNN x NNNN', '5554443333____') // => '555-444-3333 x ____'

Underscores are the only supported placeholder character.

Just call format as the phone number updates in order to get back the newly updated string. Useful for using it with a input mask setup