- Docs
- Getting started
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
npm install @samline/formatterpnpm
pnpm add @samline/formatteryarn
yarn add @samline/formatterbun
bun add @samline/formatterHTML / CDN
<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.
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
- Sent to your backend
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
<!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
.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
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
<!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
<!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
.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
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
<!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
Controlled inputs in React, Vue and Svelte, plus vanilla and server-side use.
Working examplesSix live fields with copyable files for both loading modes.
ConfigurationEvery option, with defaults and runtime impact.
RecipesEnd-to-end patterns for real forms.