Guide

Getting started

Install @samline/formatter with a package manager or from a CDN, format your first input field and submit its raw value.

Requirements

  • Node.js 20+ when you install the package with a bundler or run it on the server. The builds target ES2020.
  • Any package manager, or no package manager at all when you load the standalone script from a CDN.

Install

npm

Terminal
npm install @samline/formatter

pnpm

Terminal
pnpm add @samline/formatter

yarn

Terminal
yarn add @samline/formatter

bun

Terminal
bun add @samline/formatter

HTML / CDN

Terminal
<script src="https://cdn.jsdelivr.net/npm/@samline/formatter@3.3.1/dist/browser/formatter.phone.global.js" defer></script>

The HTML / CDN tab loads the minified standalone build with phone support, which defines window.Formatter with format, intl, regex, checks and version. Pages that format no phones can load the smaller formatter.global.js instead; see HTML / CDN.

Phone support is opt-in since 3.0.0 so bundles that never format phones skip libphonenumber-js. With a package manager, import registerPhone from @samline/formatter/phone and call it once, as below.

Quick start

import { format } from '@samline/formatter'
import { registerPhone } from '@samline/formatter/phone'

registerPhone()

// Phone (Mexico by default, space-delimited)
format('5512345678', 'phone')
// => { formatted: '55 1234 5678', raw: '5512345678', type: 'phone' }

// Numeral (thousand separators)
format('1234567', 'numeral')
// => { formatted: '1,234,567', raw: '1234567', type: 'numeral' }

// Date (a raw Y-m-d value becomes d/m/Y for display)
format('2026-05-12', 'date')
// => { formatted: '12/05/2026', raw: '2026-05-12', type: 'date' }

// Credit card (grouped by brand, digits-only raw)
format('4111111111111111', 'creditCard')
// => { formatted: '4111 1111 1111 1111', raw: '4111111111111111', type: 'creditCard' }

// Card brand detection
format('4111111111111111', 'creditCardType')
// => { formatted: 'visa', raw: '4111111111111111', type: 'creditCardType' }

Your first working field

This is the field the starter files build: type a number, change the country and watch both values update.

PhoneLive · formatted and raw

A phone number for any country

format(value, 'phone', { country })

Type or paste a number. The selected country decides the grouping; the backend receives digits, plus a leading + for international numbers.

Shown to people
55 1234 5678
Sent to your backend
5512345678

Changing the country reformats the same digits. One input listener and one change listener read the current country, so listeners never pile up.

Working starter files

These files format a phone field as people type, regroup it when the country changes and mirror the raw value into a hidden input. Save HTML, CSS and JavaScript together, or copy the complete file. Choose HTML / CDN for a page without a build step, or Package / ESM for a bundler.

HTML / CDN

HTML

index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A phone number for any country</title>
    <link rel="stylesheet" href="./style.css" />
  </head>

  <body>
    <main>
      <div class="formatter-field">
        <label for="phone-country">Country</label>
        <select id="phone-country">
          <option value="MX" selected>Mexico</option>
          <option value="US">United States</option>
          <option value="ES">Spain</option>
          <option value="GB">United Kingdom</option>
          <option value="AR">Argentina</option>
          <option value="DE">Germany</option>
        </select>
        <label for="phone">Mobile phone</label>
        <input
          id="phone"
          type="text"
          inputmode="tel"
          autocomplete="tel"
          placeholder="55 1234 5678"
          value="5512345678"
          aria-describedby="phone-raw"
        />
        <input type="hidden" name="phone" />
        <p id="phone-raw">Sent to your backend: <output data-raw></output></p>
      </div>
    </main>

    <script src="https://cdn.jsdelivr.net/npm/@samline/formatter@3.3.1/dist/browser/formatter.phone.global.js"></script>
    <script src="./main.js" defer></script>
  </body>
</html>

CSS

style.css
.formatter-field {
  display: grid;
  gap: 0.5rem;
  max-width: 24rem;
  padding: 1.5rem;
  border: 0.0625rem solid #c9d3b8;
  border-radius: 1rem;
  font:
    1rem/1.6 system-ui,
    sans-serif;
}
.formatter-field label {
  font-weight: 600;
}
.formatter-field input,
.formatter-field select {
  padding: 0.75rem 0.875rem;
  border: 0.0625rem solid #9aa58a;
  border-radius: 0.5rem;
  font: inherit;
  font-variant-numeric: tabular-nums;
}
.formatter-field select {
  cursor: pointer;
}
.formatter-field input:focus-visible,
.formatter-field select:focus-visible {
  outline: 0.125rem solid #4d7c0f;
  outline-offset: 0.125rem;
}
.formatter-field p {
  margin: 0;
  color: #4a5240;
}
.formatter-field output {
  font-family: ui-monospace, monospace;
  overflow-wrap: anywhere;
}
.formatter-field [data-status][data-valid='false'] {
  color: #9b2c2c;
}

JavaScript

main.js
const { format } = window.Formatter

const field = document.querySelector('#phone')
const hidden = document.querySelector('input[name="phone"]')
const rawOutput = document.querySelector('[data-raw]')
const country = document.querySelector('#phone-country')
const options = {}

const update = () => {
  const { formatted, raw } = format(field.value, 'phone', { ...options, country: country.value })
  field.value = formatted
  hidden.value = raw
  rawOutput.value = raw || '—'
}

field.addEventListener('input', update)
country.addEventListener('change', update)
update()

Complete file

index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A phone number for any country</title>
    <style>
      .formatter-field {
        display: grid;
        gap: 0.5rem;
        max-width: 24rem;
        padding: 1.5rem;
        border: 0.0625rem solid #c9d3b8;
        border-radius: 1rem;
        font:
          1rem/1.6 system-ui,
          sans-serif;
      }
      .formatter-field label {
        font-weight: 600;
      }
      .formatter-field input,
      .formatter-field select {
        padding: 0.75rem 0.875rem;
        border: 0.0625rem solid #9aa58a;
        border-radius: 0.5rem;
        font: inherit;
        font-variant-numeric: tabular-nums;
      }
      .formatter-field select {
        cursor: pointer;
      }
      .formatter-field input:focus-visible,
      .formatter-field select:focus-visible {
        outline: 0.125rem solid #4d7c0f;
        outline-offset: 0.125rem;
      }
      .formatter-field p {
        margin: 0;
        color: #4a5240;
      }
      .formatter-field output {
        font-family: ui-monospace, monospace;
        overflow-wrap: anywhere;
      }
      .formatter-field [data-status][data-valid='false'] {
        color: #9b2c2c;
      }
    </style>
  </head>

  <body>
    <main>
      <div class="formatter-field">
        <label for="phone-country">Country</label>
        <select id="phone-country">
          <option value="MX" selected>Mexico</option>
          <option value="US">United States</option>
          <option value="ES">Spain</option>
          <option value="GB">United Kingdom</option>
          <option value="AR">Argentina</option>
          <option value="DE">Germany</option>
        </select>
        <label for="phone">Mobile phone</label>
        <input
          id="phone"
          type="text"
          inputmode="tel"
          autocomplete="tel"
          placeholder="55 1234 5678"
          value="5512345678"
          aria-describedby="phone-raw"
        />
        <input type="hidden" name="phone" />
        <p id="phone-raw">Sent to your backend: <output data-raw></output></p>
      </div>
    </main>

    <script src="https://cdn.jsdelivr.net/npm/@samline/formatter@3.3.1/dist/browser/formatter.phone.global.js"></script>
    <script>
      const { format } = window.Formatter

      const field = document.querySelector('#phone')
      const hidden = document.querySelector('input[name="phone"]')
      const rawOutput = document.querySelector('[data-raw]')
      const country = document.querySelector('#phone-country')
      const options = {}

      const update = () => {
        const { formatted, raw } = format(field.value, 'phone', {
          ...options,
          country: country.value,
        })
        field.value = formatted
        hidden.value = raw
        rawOutput.value = raw || '—'
      }

      field.addEventListener('input', update)
      country.addEventListener('change', update)
      update()
    </script>
  </body>
</html>

Package / ESM

HTML

index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A phone number for any country</title>
    <link rel="stylesheet" href="./style.css" />
  </head>

  <body>
    <main>
      <div class="formatter-field">
        <label for="phone-country">Country</label>
        <select id="phone-country">
          <option value="MX" selected>Mexico</option>
          <option value="US">United States</option>
          <option value="ES">Spain</option>
          <option value="GB">United Kingdom</option>
          <option value="AR">Argentina</option>
          <option value="DE">Germany</option>
        </select>
        <label for="phone">Mobile phone</label>
        <input
          id="phone"
          type="text"
          inputmode="tel"
          autocomplete="tel"
          placeholder="55 1234 5678"
          value="5512345678"
          aria-describedby="phone-raw"
        />
        <input type="hidden" name="phone" />
        <p id="phone-raw">Sent to your backend: <output data-raw></output></p>
      </div>
    </main>

    <script type="module" src="./main.js"></script>
  </body>
</html>

CSS

style.css
.formatter-field {
  display: grid;
  gap: 0.5rem;
  max-width: 24rem;
  padding: 1.5rem;
  border: 0.0625rem solid #c9d3b8;
  border-radius: 1rem;
  font:
    1rem/1.6 system-ui,
    sans-serif;
}
.formatter-field label {
  font-weight: 600;
}
.formatter-field input,
.formatter-field select {
  padding: 0.75rem 0.875rem;
  border: 0.0625rem solid #9aa58a;
  border-radius: 0.5rem;
  font: inherit;
  font-variant-numeric: tabular-nums;
}
.formatter-field select {
  cursor: pointer;
}
.formatter-field input:focus-visible,
.formatter-field select:focus-visible {
  outline: 0.125rem solid #4d7c0f;
  outline-offset: 0.125rem;
}
.formatter-field p {
  margin: 0;
  color: #4a5240;
}
.formatter-field output {
  font-family: ui-monospace, monospace;
  overflow-wrap: anywhere;
}
.formatter-field [data-status][data-valid='false'] {
  color: #9b2c2c;
}

JavaScript

main.js
import { format } from '@samline/formatter'
import { registerPhone } from '@samline/formatter/phone'

registerPhone()

const field = document.querySelector('#phone')
const hidden = document.querySelector('input[name="phone"]')
const rawOutput = document.querySelector('[data-raw]')
const country = document.querySelector('#phone-country')
const options = {}

const update = () => {
  const { formatted, raw } = format(field.value, 'phone', { ...options, country: country.value })
  field.value = formatted
  hidden.value = raw
  rawOutput.value = raw || '—'
}

field.addEventListener('input', update)
country.addEventListener('change', update)
update()

Complete file

index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>A phone number for any country</title>
    <style>
      .formatter-field {
        display: grid;
        gap: 0.5rem;
        max-width: 24rem;
        padding: 1.5rem;
        border: 0.0625rem solid #c9d3b8;
        border-radius: 1rem;
        font:
          1rem/1.6 system-ui,
          sans-serif;
      }
      .formatter-field label {
        font-weight: 600;
      }
      .formatter-field input,
      .formatter-field select {
        padding: 0.75rem 0.875rem;
        border: 0.0625rem solid #9aa58a;
        border-radius: 0.5rem;
        font: inherit;
        font-variant-numeric: tabular-nums;
      }
      .formatter-field select {
        cursor: pointer;
      }
      .formatter-field input:focus-visible,
      .formatter-field select:focus-visible {
        outline: 0.125rem solid #4d7c0f;
        outline-offset: 0.125rem;
      }
      .formatter-field p {
        margin: 0;
        color: #4a5240;
      }
      .formatter-field output {
        font-family: ui-monospace, monospace;
        overflow-wrap: anywhere;
      }
      .formatter-field [data-status][data-valid='false'] {
        color: #9b2c2c;
      }
    </style>
  </head>

  <body>
    <main>
      <div class="formatter-field">
        <label for="phone-country">Country</label>
        <select id="phone-country">
          <option value="MX" selected>Mexico</option>
          <option value="US">United States</option>
          <option value="ES">Spain</option>
          <option value="GB">United Kingdom</option>
          <option value="AR">Argentina</option>
          <option value="DE">Germany</option>
        </select>
        <label for="phone">Mobile phone</label>
        <input
          id="phone"
          type="text"
          inputmode="tel"
          autocomplete="tel"
          placeholder="55 1234 5678"
          value="5512345678"
          aria-describedby="phone-raw"
        />
        <input type="hidden" name="phone" />
        <p id="phone-raw">Sent to your backend: <output data-raw></output></p>
      </div>
    </main>

    <script type="module">
      import { format } from '@samline/formatter'
      import { registerPhone } from '@samline/formatter/phone'

      registerPhone()

      const field = document.querySelector('#phone')
      const hidden = document.querySelector('input[name="phone"]')
      const rawOutput = document.querySelector('[data-raw]')
      const country = document.querySelector('#phone-country')
      const options = {}

      const update = () => {
        const { formatted, raw } = format(field.value, 'phone', {
          ...options,
          country: country.value,
        })
        field.value = formatted
        hidden.value = raw
        rawOutput.value = raw || '—'
      }

      field.addEventListener('input', update)
      country.addEventListener('change', update)
      update()
    </script>
  </body>
</html>

Ownership

Formatter owns nothing on the page. Your code owns the listener, the visible value, the hidden value, labels, error messages and caret handling. There is no instance to create or destroy: remove your own listener when the field goes away. The Styling and UX guide covers markup, input attributes and caret behavior.

Next steps