formatters()

formatters cleans a value while the user types, or prints a stored value for people or for the API.

formatters(value, name, options)

Parameter	Description
value	The value to format: text, a number, or a Date
name	A base formatter, a preset, or null to apply only the options
options	Optional. The options that change the formatting

Returns

formatters always returns a string. It returns "" when it can't read the value as a date or number.

Throws

formatters throws an error for an unknown formatter or option name, an allowChars set that uses \d, \w, or \s, or an unknown timezone.

Examples

The following examples show common calls:

formatters("air export", "titleCase")                       // "Air Export"
formatters("abcde 1234f", "pan")                            // "ABCDE1234F"
formatters("12.34567", "decimal", { decimalPlaces: 3 })     // "12.345"
formatters("2026-10-07 09:00:00", "displayDateTime")        // "07-10-2026 14:30"  (UTC shown in IST)
formatters("07-10-2026", "apiDate", { inputFormat: "DD-MM-YYYY" })   // "2026-10-07"

Base formatters

A base formatter is a single kind of transformation, such as changing case or printing a date. The package has 14 base formatters:

Formatter	What it does
trim	Removes spaces at both ends and collapses repeated spaces, but keeps line breaks, so it's safe on a text area
titleCase	Capitalizes each word and converts the rest to lower case
upperCase	Converts the text to upper case
lowerCase	Converts the text to lower case
numbersOnly	Keeps the digits 0 to 9 and removes everything else
integersOnly	Keeps digits and removes leading zeros
decimal	Keeps digits and one decimal point, turns .5 into 0.5, and cuts decimals to decimalPlaces
date	Prints a date in the form that format sets, DD-MM-YYYY by default
displayDate	Prints a date as 07-10-2026
displayDateTime	Prints a date and time as 07-10-2026 14:30, in timezone
apiDate	Prints a date as 2026-10-07, in UTC, which is what the API stores
apiDateTime	Prints a date and time as 2026-10-07 09:00:00, in UTC
currency	Prints money in the locale and currency you set, such as ₹1,25,000.00 for 125000
decimalGrouped	Prints a number with thousands grouping for the locale, such as 12,50,000

Use trim when a field loses focus or before you save. If you run it on every keystroke, it removes the space that the user is typing.

Presets

A formatter preset is a base formatter with options already set. Most formatter presets share a name with a validator preset. A field can clean itself with formatters(v, "pan") while the user types, and then be checked with validators(v, "pan"). For details, see Format and validate a form field.

The package has 17 formatter presets:

Preset	Defined as	Example
decimalUpTo1 to decimalUpTo6	decimal, with one to six decimal places	decimalUpTo2 turns 12.3456 into 12.34
amount	decimal, with two decimal places	1,250.505 becomes 1250.50
weight	decimal, with three decimal places	1500.2509 becomes 1500.250
percentage	decimal, with two decimal places and at most six characters	99.999 becomes 99.99
mobile	Digits, at most 10	98765-43210-9 becomes 9876543210
pincode	Digits, at most six	560 001 becomes 560001
email	trim, and then lowerCase	Ops@Example.COM becomes ops@example.com
pan	Upper case, letters and digits, at most 10	abcde 1234f becomes ABCDE1234F
iec	Upper case, letters and digits, at most 10	abcd 12345 f becomes ABCD12345F
gstin	Upper case, letters and digits, at most 15	27abcde1234f1z5 becomes 27ABCDE1234F1Z5
ifsc	Upper case, letters and digits, at most 11	hdfc 0001234 becomes HDFC0001234
vehicleNumber	Upper case, letters and digits, at most 10	ka-01 ab 1234 becomes KA01AB1234

Your options override a preset's options, for example formatters(v, "pan", { maxLength: 12 }).

Options

Each option changes one step of the formatting:

Option	Applies to	Meaning
allowChars	All	Keeps only these characters, written as a character set such as "0-9+()/, -"; don't use \d, \w, or \s
decimalPlaces	decimal	The number of digits kept after the decimal point
decimalPlaces	currency, decimalGrouped	The number of decimals shown
allowNegative	decimal	Keeps one leading -, as in -18.5
maxLength	All	Cuts the result to this many characters
locale	currency, decimalGrouped	The locale, such as "en-IN" (default)
currency	currency	The currency, such as "INR" (default)
format	Dates	The output pattern, built from the tokens YYYY, YY, MM, MMM, DD, HH, hh, mm, ss, and A
timezone	Dates	The zone to print in: Asia/Kolkata (default), UTC, or an offset such as "+05:30"
inputFormat	Dates	The pattern of the text being read, such as "DD-MM-YYYY"
inputTimezone	Dates	The zone the text was typed in; the default is Asia/Kolkata

The steps run in this order:

1. allowChars
2. The formatter
3. decimalPlaces
4. maxLength

The following examples use options:

formatters("+91 (80) 1234-5678#", null, { allowChars: "0-9+()/, -" })      // "+91 (80) 1234-5678"
formatters("-18.567", "decimal", { allowNegative: true, decimalPlaces: 1 }) // "-18.5"
formatters("2026-10-07 09:00:00", "date", { format: "DD MMM YYYY, hh:mm A" })

Locale data

currency and decimalGrouped use each platform's own locale data: the browser or Node in JavaScript, and the Babel library in Python. Their output can differ slightly between platforms.

Related topics

• Format and validate a form field
• Work with dates and time zones
• validators()