JavaScript Number toLocaleString() Method

Definition and Usage

toLocaleString() Return the number as a string using the local language format.

The language format depends on the region settings on your computer.

Instance

Example 1

Use the region setting to format the number as a string:

let num = 1000000;
let text = num.toLocaleString();

Try it yourself

Example 2

Use the specific language environment of Finland to format the number as a string:

let num = 1000000;
let text = num.toLocaleString("fi-FI");

Try it yourself

Example 3

Use the specific language environment of the United States to format the number as a currency string:

let num = 1000000;
let text = num.toLocaleString("en-US", {style:"currency", currency:"USD"});

Try it yourself

Example 4

Use options Parameter (object) for currency formatting:

let num = new Number(1000000);
const myObj = {
  style: "currency",
  currency: "EUR"
}
let text = num.toLocaleString("en-GB", myObj);

Try it yourself

Example 5

let num = new Number(1000000);
let text = num.toLocaleString("en-GB", {style:"currency", currency:"EUR"});

Try it yourself

Example 6

Use the specific language environment of JAPAN:

let num = 1000000;
let text = num.toLocaleString("ja-JP", {style:"currency", currency:"JPY"});

Try it yourself

Grammar

number.toLocaleString(locales, options)

Parameter

Parameter Description
locales Optional. The language-specific format to use. See the table below.
options Optional. An object with format options. See the table below.

locales The acceptable values for the parameter:

  • ar-SA Arabic (Saudi Arabia)
  • bn-BD Bengali (Bangladesh)
  • bn-IN Bengali (India)
  • cs-CZ Czech (Czech Republic)
  • da-DK Danish (Denmark)
  • de-AT Austrian German
  • de-CH German "Switzerland"
  • de-DE Standard German (used in Germany)
  • el-GR Modern Greek
  • en-AU Australian English
  • en-CA Canadian English
  • en-GB British English
  • en-IE Irish English
  • en-IN Indian English
  • en-NZ New Zealand English
  • en-US American English
  • en-ZA English (South Africa)
  • es-AR Argentinian Spanish
  • es-CL Chilean Spanish
  • es-CO Colombian Spanish
  • es-ES Castilian Spanish (used in northern and central Spain)
  • es-MX Mexican Spanish
  • es-US American Spanish
  • fi-FI Finnish (Finland)
  • fr-BE Belgian French
  • fr-CA Canadian French
  • fr-CH French "Switzerland"
  • fr-FR Standard French (especially in France)
  • he-IL Hebrew (Israel)
  • hi-IN Hindi (India)
  • hu-HU Hungarian (Hungary)
  • id-ID Indonesian (Indonesia)
  • it-CH “Swiss” Italian
  • it-IT Standard Italian (used in Italy)
  • ja-JP Japanese (Japan)
  • ko-KR Korean (Republic of Korea)
  • nl-BE Flemish Dutch
  • nl-NL Standard Dutch (Dutch)
  • no-NO Norwegian (Norway)
  • pl-PL Polish (Poland)
  • pt-BR Brazilian Portuguese
  • pt-PT European Portuguese (Portuguese written and spoken)
  • ro-RO Romanian (Romania)
  • ru-RU Russian (Russian Federation)
  • sk-SK Slovak (Slovakia)
  • sv-SE Swedish (Sweden)
  • ta-IN Tamil (India)
  • ta-LK Sinhala (Sri Lanka)
  • th-TH Thai (Thailand)
  • tr-TR Turkish (Turkey)
  • zh-CN Mainland China, simplified characters
  • zh-HK Hong Kong, traditional characters
  • zh-TW Taiwan, traditional characters

options Options accepted by the parameter:

Options Value
currency Valid values: any currency code (such as "EUR", "USD", "INR", etc.)
currencyDisplay

Valid values:

  • "symbol"(Default)
  • "code"
  • "name"
localeMatcher

Valid values:

  • "best-fit"(Default)
  • "lookup"
maximumFractionDigits A number from 0 to 20 (default is 3)
maximumSignificantDigits A number from 1 to 21 (default is 21)
minimumFractionDigits A number from 0 to 20 (default is 3)
minimumIntegerDigits A number from 1 to 21 (default is 1)
minimumSignificantDigits A number from 1 to 21 (default is 21)
style

Valid values:

  • "currency"
  • "decimal"(Default)
  • "percent"
useGrouping

Valid values:

  • "true"(Default)
  • "false"

Return value

Type Description
String String representing the locally formatted number.

Technical details

Return value

The string representation of a number, determined by the implementation, formatted according to the local conventions, which may affect the punctuation used for the decimal point or the thousands separator.

Thrown

Exception Description
TypeError An exception is thrown if the object called this method is not a Number.

Browser support

toLocaleString() It is a feature of ECMAScript3 (ES3).

All browsers fully support ES3 (JavaScript 1999):

Chrome IE Edge Firefox Safari Opera
Chrome IE Edge Firefox Safari Opera
Support Support Support Support Support Support