number

A Number, BigInt, or string, to format.

Strings are parsed as string numeric literals (as defined by the ECMA-262 "StringNumericLiteral" grammar). These support, among other things, the general syntax for decimal strings #.#E#, and non-base-10 numbers like hexadecimal and binary. String values passed to the format() function:

• may have leading and/or trailing white space and/or line terminators.
• may have any number of leading 0 digits.
• may include a "+" or "-" character to indicate its sign.
• may be empty or whitespace-only. In this case the value is converted to +0.
• may include Infinity or -Infinity.
• cannot be suffixed with n (the suffix used to indicate that a numeric value is a BigInt)
• cannot include a numeric literal separator (_).

The format() method formats a number into a string according to the locale and formatting options of this Intl.NumberFormat object.

Number values in JavaScript suffer from loss of precision if they are too big or too small, making the text representation inaccurate. If you are performing calculations with integers larger than Number.MAX_SAFE_INTEGER you should use a BigInt instead, which will format correctly:

new Intl.NumberFormat('en-US').format(1234567891234567891) // 1,234,567,891,234,568,000
new Intl.NumberFormat('en-US').format(1234567891234567891n) // 1,234,567,891,234,567,891

You can also pass through very large strings to be formatted as an arbitrary-precision decimal string (if you're performing calculations on the data you will still need to work with BigInt):

new Intl.NumberFormat('en-US').format("1234567891234567891") // 1,234,567,891,234,567,891

Use the format getter function for formatting a single currency value. The code below shows how to format the roubles currency for a Russian locale:

const options = { style: 'currency', currency: 'RUB' };
const numberFormat = new Intl.NumberFormat('ru-RU', options);
console.log(numberFormat.format(654321.987));
// → "654 321,99 ₽"

Use the format getter function for formatting all numbers in an array. Note that the function is bound to the Intl.NumberFormat from which it was obtained, so it can be passed directly to Array.prototype.map. This is considered a historical artefact, as part of a convention which is no longer followed for new features, but is preserved to maintain compatibility with existing programs.

const a = [123456.789, 987654.321, 456789.123];
const numberFormat = new Intl.NumberFormat('es-ES');
const formatted = a.map((n) => numberFormat.format(n));
console.log(formatted.join('; '));
// → "123.456,789; 987.654,321; 456.789,123"

Using a string we can specify very numbers that are larger than Number.MAX_SAFE_INTEGER without losing precision.

const numberFormat = new Intl.NumberFormat("en-US");

// Here the value is converted to a Number
console.log(numberFormat.format(987654321987654321))
// → 987,654,321,987,654,300

// Here we use a string and don't lose precision
console.log(numberFormat.format("987654321987654321"));
// → 987,654,321,987,654,321

We can also use the general "E" exponent syntax for decimal strings: #.#E#. The code below creates a BigInt, coerces it to a string with the suffix E-6, and then formats it.

const numberFormat = new Intl.NumberFormat("en-US");
const bigNum = 1000000000000000110000n;
console.log(numberFormat.format(bigNum));
// → "1,000,000,000,000,000,110,000"

// Format as a string using the `E` syntax:
console.log(numberFormat.format(`${bigNum}E-6`));
// → "1,000,000,000,000,000.11"

• Intl.NumberFormat
• Number.prototype.toLocaleString()