Two outputs, one call
format() returns formatted for the visible field and raw for the hidden input or request body, so the two never drift apart.
Input formatting for the fields that matter.
Group a phone, price a total, or store a date as ISO.
npm install @samline/formatterOne pure functionJavaScript & TypeScriptMIT licensed
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.
Changing the country reformats the same digits. One input listener and one change listener read the current country, so listeners never pile up.
An amount with currency and decimals
format(value, 'numeral', { prefix, numeralDecimalScale })Thousands separators and a currency prefix appear while typing. The raw value is a plain decimal string ready to parse on the server.
numeralDecimalScale limits the decimals. The prefix is display-only: raw never includes it. regex.numeral(options) takes the same options, so the rule accepts exactly what the mask writes.
A date shown locally, stored as ISO
format(value, 'date', { datePattern, delimiter, dateRawPattern, dateRawPatternDelimiter })People read day/month/year; the API stores year-month-day. A server value such as 1990-12-31 is recognized and converted for display.
interpretInputAs: "auto" treats a complete value without the display delimiter as raw. Partial or delimited values are treated as typing.
A card number with its brand
format(value, 'creditCard')Grouping follows the detected card brand. The same digits drive a brand badge and a paired validation message.
creditCardType returns the brand as formatted and the digits as raw. Formatting is not payment validation: rely on your payment provider for that.
An order reference with a fixed prefix
format(value, 'general', { prefix, blocks, delimiter, numericOnly })The ORD- prefix is locked, digits are grouped by blocks, and the backend receives only the digits. Deleting part of the prefix restores it.
Pasted values that already include the prefix are accepted. Add rawPrefix: true when the backend stores ORD- as part of the value.
Validation rules with ready messages
regex[rule].pattern.test(value)Choose a rule from the regex catalog and type a value. Each rule pairs its pattern with the message to show, so the two never drift apart.
Static rules are records; parametric ones such as password() are called first. Validate again on the server: these patterns give quick feedback.
ONE SMALL SCRIPT. RIGHT AT HOME IN YOUR STACK.
format() returns formatted for the visible field and raw for the hidden input or request body, so the two never drift apart.
Formatter never touches the DOM. Labels, error messages, autocomplete, inputmode and caret behavior stay under your control.
There is no instance to create or destroy. Call it on every input event, on the server, or in a test with the same result.
Numerals, dates, times, card numbers and brands, and general block masks from a built-in engine, plus opt-in phones through libphonenumber-js.
Store raw in state and render formatted. The same call works in React, Vue, Svelte, vanilla JavaScript and server code.
The regex catalog pairs each pattern with its error message, including parametric rules for digits, phones, cards, URLs and passwords.
Every entrypoint exposes the same format() and regex. Pick the one that matches how your project loads JavaScript.
Package / ESM
ES module and CommonJS builds with bundled type declarations.
Explicit subpath
The same API under a stable name for projects that pin a runtime subpath.
HTML / CDN
A minified standalone script for pages without a bundler, including CMS themes.
Browser global
The standalone script defines format, intl, regex, checks and version on one global.
Types
FormatType, RegexKey, DatePatternType and every option are exported.
Styles
Nothing to import: the package returns strings and your CSS styles the field.
Format the visible input on every keystroke and mirror the raw value into a hidden input that your form submits.
Read the installation guideInstall
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>Add two inputs
A visible field for people and a hidden field with the name your backend reads.
<label for="phone">Mobile phone</label>
<input id="phone" type="text" inputmode="tel" autocomplete="tel" />
<input type="hidden" name="phone" />
Format on input
import { format } from '@samline/formatter'
import { registerPhone } from '@samline/formatter/phone'
registerPhone()
const field = document.querySelector('#phone')
const hidden = document.querySelector('input[name="phone"]')
field.addEventListener('input', () => {
const { formatted, raw } = format(field.value, 'phone', { country: 'MX' })
field.value = formatted
hidden.value = raw
})
const { format } = window.Formatter
const field = document.querySelector('#phone')
const hidden = document.querySelector('input[name="phone"]')
field.addEventListener('input', () => {
const { formatted, raw } = format(field.value, 'phone', { country: 'MX' })
field.value = formatted
hidden.value = raw
})
Load the CDN script from step 1 first, then this file with defer. window.Formatter replaces the import.
Continue with every option, the regex catalog and the TypeScript types.
Explore the configuration referencePatterns that come up in real forms: server-filled values, regional numbers, stored values and validation messages.
A stored ISO date has no display delimiter, so the default auto mode treats it as raw and converts it for display.
Read about interpretInputAsconst { formatted } = format('1990-12-31', 'date', {
datePattern: ['d', 'm', 'Y'],
delimiter: '/',
dateRawPattern: ['Y', 'm', 'd'],
dateRawPatternDelimiter: '-',
})
field.value = formatted // '31/12/1990'Swap the decimal mark and grouping delimiter for European amounts. The raw value always uses a dot.
Read the numeral optionsformat('1234567,891', 'numeral', {
numeralDecimalMark: ',',
delimiter: '.',
numeralDecimalScale: 2,
})
// { formatted: '1.234.567,89', raw: '1234567.89', type: 'numeral' }Show stored amounts and dates in the reader’s locale with the Intl helpers. Empty or unreadable values return an empty string, never NaN.
Read about the Intl helpersimport { formatCurrency, formatDate } from '@samline/formatter/intl'
formatCurrency('1234.5', { locale: 'es-MX', currency: 'MXN' }) // '$1,234.50'
formatDate('2026-11-12', { locale: 'es-MX', preset: 'long' }) // '12 de noviembre de 2026'
formatCurrency(null, { currency: 'MXN' }) // ''Test the raw value and show the message that belongs to the same rule through the native constraint API.
Explore the regex catalogimport { format, regex } from '@samline/formatter'
import { registerPhone } from '@samline/formatter/phone'
registerPhone()
field.addEventListener('input', () => {
const { formatted, raw } = format(field.value, 'phone')
const rule = regex.phone({ length: 10 })
field.value = formatted
field.setCustomValidity(rule.pattern.test(raw) ? '' : rule.errorMessage)
})Try a working field or format your first input.
Installation, practical guides and the complete API for Formatter 3.3.1.
Read the documentation