CKTIS / JavaScript
Intl.NumberFormat: currency and percent options
Format amounts and ratios for a locale. Learn when a currency code is mandatory, why 0.125 represents 12.5%, and how to control the digits after the decimal separator.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
new Intl.NumberFormat(locale, { style: "currency", currency: "USD" }).format(amount)
new Intl.NumberFormat(locale, { style: "percent", minimumFractionDigits: 1, maximumFractionDigits: 1 }).format(ratio)new Intl.NumberFormat(locale, options) creates a reusable formatter; format(value) returns localized text. The locale affects details such as separators and symbol placement, while style selects what kind of display you want. If you omit style, it defaults to "decimal".
With style: "currency", set currency to a code such as "USD". Pass the amount in major units, not cents: formatting does not convert currencies. An omitted code throws TypeError; a code that is not three ASCII letters throws RangeError. A well-formed code is not necessarily an assigned currency code. currencyDisplay selects "symbol" (the default), "narrowSymbol", "code", or "name". currencySign defaults to "standard"; "accounting" can show negative amounts in parentheses, depending on the locale.
With style: "percent", pass a ratio: formatting multiplies it by 100 before rounding. To display 12.5%, pass 0.125, not 12.5. With standard notation and no significant-digit settings, currency defaults to the number of fraction digits for its minor unit (two for USD), while percent defaults to zero fraction digits. minimumFractionDigits pads with zeros as needed, and maximumFractionDigits limits the precision used for rounding. With the default trailingZeroDisplay: "auto", set both to the same value to show exactly that many fraction digits. With trailingZeroDisplay: "stripIfInteger", the fractional part is omitted if the rounded result is an integer.
Locale data and runtime support can vary. Spacing and symbols may differ even for the same locale, so avoid comparing the complete localized string to a hardcoded value. Use formatToParts() to inspect components by type.
Examples
const locale = "en-US-u-nu-latn";
const money = new Intl.NumberFormat(locale, {
style: "currency",
currency: "USD",
currencyDisplay: "code",
});
const percent = new Intl.NumberFormat(locale, {
style: "percent",
minimumFractionDigits: 1,
maximumFractionDigits: 1,
});
const moneyParts = money.formatToParts(19.9);
const percentParts = percent.formatToParts(0.125);
const valueOf = (parts, type) => parts.find(part => part.type === type)?.value;
console.log(JSON.stringify([
valueOf(moneyParts, "currency"),
valueOf(moneyParts, "integer"),
valueOf(moneyParts, "fraction"),
]));
console.log(JSON.stringify([
valueOf(percentParts, "integer"),
valueOf(percentParts, "fraction"),
percentParts.some(part => part.type === "percentSign"),
]));Result
["USD","19","90"] ["12","5",true]
The first line shows the USD code and the two parts of the amount, including the trailing zero. The second shows the numeric parts of 12.5% and confirms that a percent sign is present without checking its exact character or placement.
Related lessons
- JavaScript · Lesson 24 · Intermediate · Version: 3