Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท Number and BigInt

Number.prototype.toLocaleString() method

Reference for Number.prototype.toLocaleString(): format numbers, currency, percentages and units for a locale using Intl.NumberFormat options.

toLocaleString() returns a string that formats a number the way people in a given language and region expect to read it: the right thousands separator, decimal mark, digit shapes, currency symbol or percent sign. The same number prints as 1,234.5 in US English and 1.234,5 in German.

It accepts a locale and an options object. Both are passed to Intl.NumberFormat, so everything that object can do is available here too.

JavaScript
(1234567.891).toLocaleString("en-US");  // "1,234,567.891"
(1234567.891).toLocaleString("de-DE");  // "1.234.567,891"

Try it

JS Locales and currency

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

No output.

JS Digits, percent, units and compact

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

No output.

Syntax

JavaScript
numberValue.toLocaleString()
numberValue.toLocaleString(locales)
numberValue.toLocaleString(locales, options)
Name Description
locales Optional. A BCP 47 language tag such as "en-US" or "fr-FR", or an array of tags in order of preference. If omitted, the runtime's default locale is used.
options Optional. An object with Intl.NumberFormat options, such as style, currency, unit, notation, minimumFractionDigits, maximumFractionDigits, useGrouping and signDisplay.

Return value: a formatted string.

Exceptions: a RangeError for an invalid locale tag or an invalid option value (for example an unknown currency code or maximumFractionDigits outside the allowed range). A TypeError if style is "currency" but no currency is given.

Usage notes

  • Pass the locale explicitly when output must be predictable, for example in tests or server-rendered pages. With no argument, the result depends on the user's environment.
  • For many numbers, create one Intl.NumberFormat and call its format(). Each toLocaleString() call with options builds a formatter again, so a reused formatter is faster in loops.
  • Currency needs both options: style: "currency" and a currency code. The code decides the symbol and the usual number of decimals (zero for the yen, two for dollars).
  • Rounding follows the fraction-digit options, not the stored value, so the result can differ from a value you computed yourself. For money, keep amounts as integer cents and format at the end.
  • The output is for people, not parsers. Do not feed a localized string to Number() or parseFloat(); the separators differ by locale.
  • Exact text can vary between engines and library versions, especially for less common locales. Test with the locales you ship.
  • Dates have their own method: Date.prototype.toLocaleString() is unrelated, though it follows the same locale idea.

Browser support

toLocaleString() with locales and options is supported in every current browser and runtime. Newer Intl.NumberFormat options and units can be more recent, so check a compatibility table for the one you need.