JavaScript Reference ยท Date and Intl
Intl.NumberFormat
Reference for JavaScript Intl.NumberFormat: format numbers, currency, percentages, units and compact notation for any locale, with options and examples.
Intl.NumberFormat creates a formatter that turns numbers into text following the rules of a language and region: digit grouping, decimal separators, currency symbols and their position, percent signs, units and abbreviations like "1.2K". The same number 1234567.891 is 1,234,567.891 in the United States, 1.234.567,891 in Germany and 12,34,567.891 in India.
You create the formatter once with a locale and options, then call format() as many times as you like. It is also the engine behind Number.prototype.toLocaleString().
const price = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }); price.format(1234.5); // "$1,234.50"
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
new Intl.NumberFormat() new Intl.NumberFormat(locales) new Intl.NumberFormat(locales, options) formatter.format(number) formatter.formatToParts(number) formatter.formatRange(start, end) formatter.resolvedOptions() Intl.NumberFormat.supportedLocalesOf(locales)
| Option | Description |
|---|---|
style |
"decimal" (default), "currency", "percent" or "unit". |
currency |
An ISO 4217 code such as "USD". Required for style: "currency". |
currencyDisplay |
"symbol" (default), "narrowSymbol", "code" or "name". |
unit, unitDisplay |
A sanctioned unit such as "kilometer" or "liter" (and "x-per-y" combinations); display "short", "narrow" or "long". |
notation |
"standard", "scientific", "engineering" or "compact" (with compactDisplay: "short" | "long"). |
minimumFractionDigits, maximumFractionDigits |
Digits after the decimal point. Currencies default to their usual number (2 for USD, 0 for JPY). |
minimumIntegerDigits |
Pads with leading zeros. |
maximumSignificantDigits, minimumSignificantDigits |
Rounds to a number of significant digits instead. |
useGrouping |
Turns thousands separators on or off. |
signDisplay |
"auto", "always", "exceptZero", "negative" or "never". |
Return value: the constructor returns a formatter object. format() returns a string. formatToParts() returns an array of { type, value } objects (types such as integer, group, decimal, fraction, currency, literal, minusSign).
Exceptions: a RangeError for an invalid locale or option value, and a TypeError if style is "currency" without currency, or "unit" without unit.
Usage notes
formatis a bound getter, so you can pass it directly:[1, 2, 3].map(formatter.format).- Reuse the formatter. Creating one is more expensive than calling
format(). Build it once (at module level) and share it. - Rounding: the default is rounding half away from zero, and the number of decimals is limited by the options, not by the input.
maximumFractionDigits: 0formats2.5as3. - BigInt and strings work.
format()accepts aBigInt, and newer engines also accept numeric strings, which avoids precision loss for very large decimal values. - Money needs care. The formatter only displays amounts. Calculate with integer cents or a decimal library, then format the result.
- Whitespace in output. Many locales put a no-break space between the number and the currency (
1.234,50 โฌ). Do not compare formatted text with plain-space literals, and never parse it. - Compact notation gives locale-specific abbreviations ("1.2K", "1,2 Mio.") and rounds to two significant digits by default.
- Data comes from the engine. Exact symbols and spacing can change between versions, so do not use the output in tests that must stay stable across platforms.
Browser support
Intl.NumberFormat basics, currency and percent formatting work in all modern browsers and runtimes. Options such as unit, notation, signDisplay and formatRange() are newer, so check a compatibility table if you support older browsers.