JS: Number.prototype.toLocaleString

Number.prototype.toLocaleString

Number.prototype.toLocaleString

Return a string that represents this number, formatted according to the conventions of the host environment's current locale.

such as digits group separator, decimal point marker, currency symbols, percentage, etc.

Basic Syntax

• number.toLocaleString()
• number.toLocaleString(locales)
• number.toLocaleString(locales, options)

parameters

locales

A string or array of “BCP 47 language tag” or an array of locale strings. If omitted, it uses the user's browser/system default locale.

e.g. "en-US" or ["zh-Hans", "en-US"]

if given array, it will use the first supported locale.

common BCP 47 language tags:

en-US → English, USA
en-GB → English, Brit

es-ES → Spanish
es-MX → Spanish, Mexican

de-DE → German
fr-FR → French

pt-BR → Portuguese
pt-PT → Portuguese

it-IT → italian
nl-NL → Dutch
pl-PL → Polish

ru-RU → Russian

zh-CN → Chinese, China
zh-Hans → Chinese, simplified characters
zh-Hant → Chinese, traditional characters
ja-JP → Japanese
ko → Korean

ar → Arabic
tr → Turkish

options

An object to customize formatting (style, currency, minimum/maximum digits, etc.).

example. number separator

// default. use browser locale
console.log((262457.086).toLocaleString());
// 262,457.086

// s------------------------------

console.log((262457.086).toLocaleString("en-US"));
// 262,457.086

// germany
console.log((262457.086).toLocaleString("de-DE"));
// 262.457,086

// france
console.log((262457.086).toLocaleString("fr-FR"));
// 262 457,086

// Arabic in Egypt
console.log((262457.086).toLocaleString("ar-EG"));
// ٢٦٢٬٤٥٧٫٠٨٦

example. Currency Formatting

console.log((4795.99).toLocaleString("en-US", {
 style: "currency",
 currency: "USD",
}));
// $4,795.99

console.log((4795.99).toLocaleString("de-DE", {
 style: "currency",
 currency: "EUR",
}));
// 4.795,99 €

console.log((4795.99).toLocaleString("en-GB", {
 style: "currency",
 currency: "GBP",
 currencyDisplay: "code",
}));
// GBP 4,795.99

example. Percentages

console.log((0.1089).toLocaleString("en-US", {
 style: "percent",
}));
// 11%

console.log((0.1089).toLocaleString("en-US", {
 style: "percent",
 minimumFractionDigits: 2,
 maximumFractionDigits: 2,
}));
// 10.89%

example. Metric prefix

console.log((5_601).toLocaleString("en-US", { notation: "compact" }));
// 5.6K

console.log((365_601).toLocaleString("en-US", { notation: "compact" }));
// 366K

console.log((3_365_601).toLocaleString("en-US", { notation: "compact" }));
// 3.4M

console.log((9_403_365_601).toLocaleString("en-US", { notation: "compact" }));
// 9.4B

// s------------------------------

console.log((9_403_365_601).toLocaleString("en-US", {
 notation: "compact",
 compactDisplay: "long",
}));
// 9.4 billion

Example. Fixed Decimal Places

console.log((327.2988).toLocaleString("en-US", {
 minimumFractionDigits: 3,
 maximumFractionDigits: 3,
}));
// 327.299

console.log((327.2988).toLocaleString("en-US", {
 minimumFractionDigits: 0,
 maximumFractionDigits: 0,
}));
// 327

Example. Unit Formatting

console.log((42.5).toLocaleString("en-US", {
 style: "unit",
 unit: "kilometer-per-hour",
 unitDisplay: "long",
}));
// 42.5 kilometers per hour

The options Object

ai answer

style

'decimal' (default), 'currency', 'percent', 'unit'◆ Main formatting style

currency

ISO currency code (e.g. 'USD', 'EUR', 'JPY')◆ Required when style: 'currency'

currencyDisplay

'symbol' (default), 'narrowSymbol', 'code', 'name'◆ How currency is shown

minimumFractionDigits

0 to 100◆ Minimum decimal places

maximumFractionDigits

0 to 100◆ Maximum decimal places

minimumIntegerDigits

1 to 21◆ Minimum digits before decimal

useGrouping

true/false◆ Show thousands separators

notation

'standard', 'scientific', 'engineering', 'compact'◆ Compact notation (1.2K, 1.2M, etc.)

compactDisplay

'short', 'long'◆ Used with notation: 'compact'

Relation to Intl.NumberFormat

toLocaleString() is a convenience wrapper around new Intl.NumberFormat(locales, options).format(number)

Reusable Formatter

For repeated formatting, create the Intl.NumberFormat instance once and reuse it for better performance.

const currencyFormatter = new Intl.NumberFormat("en-US", {
 style: "currency",
 currency: "USD",
});

console.log(currencyFormatter.format(1234.56)); // "$1,234.56"

• JS: Intl.NumberFormat