Skip to content
Tutorials Center
My learning

Topics

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().

JavaScript
const price = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" });
price.format(1234.5); // "$1,234.50"

Try it

JS Numbers in different locales

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Currency, units and compact notation

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
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

  • format is 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: 0 formats 2.5 as 3.
  • BigInt and strings work. format() accepts a BigInt, 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.