totn JavaScript

JavaScript: Number toLocaleString() method

This JavaScript tutorial explains how to use the Number method called toLocaleString() with syntax and examples.

Description

In JavaScript, toLocaleString() is a Number method that is used to convert a number into a locale-specific numeric representation of the number (rounding the result where necessary) and return its value as a string. Because toLocaleString() is a method of the Number object, it must be invoked through a particular instance of the Number class.

Syntax

In JavaScript, the syntax for the toLocaleString() method is:

number.toLocaleString([locale [, options]]);

Parameters or Arguments

locale
Optional. It is a BCP 47 language tag or an array of such tags that will be used to determine the numeric representation of the number. A BCP 47 language tag defines a language that may contain a primary language code as well as an extension. If this parameter is not provided, the toLocaleString() method will use the host environment's current locale.
options

Optional. The options to apply. It can be one or more of the following:

Value Description
localeMatcher

Determines the locale matching algorithm to use. It can be one of the following values:

  • lookup
  • best fit (default)
style

Determines the formatting style to use. It can be one of the following values:

  • decimal - general number formatting (default)
  • currency - currency formatting
  • percent - percent formatting
currency

Determines the currency formatting to use. It can be one of the 3-digit alphabetic currency codes from the ISO 4217 Currency Codes. For example, EUR for Euro, USD for US Dollar, or INR for Indian Rupee (See list of ISO 4217 currency codes).

currencyDisplay

Determines the how to display the currency formatting. It can be one of the following values:

  • symbol - use locale-specific currency symbol such as "$" (default)
  • code - use the ISO currency code such as "USD"
  • name - use the locale-specific currency name such as "dollar"
useGrouping

Determines whether to display grouping separators. It can be one of the following values:

  • true - grouping separators will be displayed (default)
  • false - grouping separators will not be displayed
minimumIntegerDigits

Determines the minimum number of integer digits to display. It can be a value between 1 and 21. If omitted, the default is 1.
minimumFractionDigits

Determines the minimum number of fractional digits to display. It can be a value between 0 and 20. If omitted, the default for decimal is 0, the default for percent is 0, and the default for currency is the "minor unit" value for the specified ISO 4217 currency code.
maximumFractionDigits

Determines the maximum number of fractional digits to display. It can be a value between 0 and 20. If omitted, the default for decimal is the larger of 3 and the minimumFractionDigits, the default for percent is the larger value of 0 and minimumFractionDigits, and the default for currency is the larger of the "minor unit" value for the specified ISO 4217 currency code and the minimumFractionDigits.
minimumSignificantDigits

Determines the minimum number of significant digits to display. It can be a value between 1 and 21. If omitted, the default is 1.
maximumSignificantDigits

Determines the maximum number of significant digits to display. It can be a value between 1 and 21. If omitted, the default is 21.

Returns

The toLocaleString() method converts a number to a locale-specific representation of the number (rounding the result where necessary) and then returns its value as a string.

Note

  • The toLocaleString() method will round the resulting value if necessary.
  • The toLocaleString() method does not change the value of the original number.

Example

Let's take a look at an example of how to use the toLocaleString() method in JavaScript.

For example:

var totn_number = 123456.789;

console.log(totn_number.toLocaleString());

In this example, we have declared a variable called totn_number that is assigned the value of 123456.789. We have then invoked the toLocaleString() method of the totn_number to convert a number into a locale-specific numeric representation of the number.

We have written the output of the toLocaleString() method to the web browser console log, for demonstration purposes, to show what the toLocaleString() method returns.

The following will be output to the web browser console log:

123,456.789

In this example, the output to the console log returned the string value "123,456.789" which is the locale-specific numeric representation for the number 123456.789 (ie: defaults to the host environment's current locale).

Specifying a Locale Parameter

You can also provide a BCP 47 language tag for the locale parameter to change the locale used to convert the number.

For example:

var totn_number = 123456.789;

console.log(totn_number.toLocaleString('en-US'));
console.log(totn_number.toLocaleString('en-IN'));
console.log(totn_number.toLocaleString('fr-FR'));

The following will be output to the web browser console log:

123,456.789
1,23,456.789
123 456,789

In this example, the first output to the console log returned "123,456.789" which is the US (English) numeric representation of the number as specified by the 'en-US' locale parameter.

The second output to the console log returned "1,23,456.789" which is the India (English) numeric representation of the number as specified by the 'en-IN' locale parameter.

The third output to the console log returned "123?456,789" which is the France (French) numeric representation of the number as specified by the 'fr-FR' locale parameter.

Specifying an Option Parameter

Finally, the toLocaleString() method has many options that you can set to change the numeric representation.

For example:

var totn_number = 123456.789;

console.log(totn_number.toLocaleString('en-US', {style:'currency', currency:'USD'}));
console.log(totn_number.toLocaleString('en-IN', {style:'currency', currency:'INR'}));
console.log(totn_number.toLocaleString('fr-FR', {style:'currency', currency:'EUR'}));

The following will be output to the web browser console log:

$123,456.79
₹ 1,23,456.79
123 456,79 €

In this example, the first output to the console log returned "$123,456.79" which is the US (English) numeric representation of the number as displayed in USD currency (which is US Dollar). Notice that the value was rounded to 2 decimal places.

The second output to the console log returned "₹ 1,23,456.79" which is the India (English) numeric representation of the number as displayed in INR currency (which is Indian Rupee). Notice that the value was rounded to 2 decimal places.

The third output to the console log returned "123 456,79 €" which is the France (French) numeric representation of the number as displayed in EUR currency (which is Euro). Notice that the value was rounded to 2 decimal places.

Share on: