Source @ github

Number.toLocaleString

toLocaleString — Returns a string representation of the specified Number object.

Description

Number.toLocaleString([mixed locales, [object options]])

Parameters

Name Description Type Default Optional
locales A string or array containing strings for the preferred locale format. mixed Yes
options See options below. object Yes
Options parameter

The options parameter may contain one or more of the following data items.

localeMatcher

Possible values are: "best fit" (default) or "lookup".

style

Possible values are: "decimal" (default), "currency" or "percent". The currency parameter is also required if this value is set to the value "currency".

currency

Possible values are the ISO 4217 currency codes. External references: currency-iso.org XML file of codes. See "Ccy" element value and currency-iso.org Current currency & funds code list page.

currencyDisplay

Possible values are: "symbol" (default) or "name".

useGrouping

Possible values are: true (default) or false.

minimumIntegerDigits

Possible values are from 1 (default) to 21.

minimumFractionDigits

Possible values are from 0 to 20.

Default values:

  • Decimal: 0.

  • Currency: The default follows the selected currency rules. If none is supplied by the currency it will fall back to 2.

  • Percent: 0.

maximumFractionDigits

Possible values are from 0 to 20.

Default values (If minimumFractionDigits is larger than the default value below then it will be used instead):

  • Decimal: 3.

  • Currency: The default follows the selected currency rules. If none is supplied by the currency it will fall back to 2.

  • Percent: 0.

minimumSignificantDigits

Possible values are from 1 (default) to 21.

If this value is specified, minimumIntegerDigits, minimumFractionDigits and maximumFractionDigits is ignored.

maximumSignificantDigits

Possible values are from 1 to 21.

The default value is minimumSignificantDigits.

If this value is specified, minimumIntegerDigits, minimumFractionDigits and maximumFractionDigits is ignored.

Return values

A string representation of the number formatted to the parameters given.

The returned value will be of the primitive string type.

Changelog

Version Description
ES 5.1 When arguments is provided a rangeError exception is now required for result out of bounds.

Examples

Example #1 – toLocalString example
var n = new Number(1234567.123);
console.log(n.toLocaleString());         // Detects the locale automatically.
console.log(n.toLocaleString('en-US'));  // 1,234,567.123
console.log(n.toLocaleString('nb-NO'));  // 1 234 567,123
console.log(n.toLocaleString('ar-EG'));  // ١٬٢٣٤٬٥٦٧٫١٢٣
console.log(n.toLocaleString('de-DE'));  // 1.234.567,123
Example #2 – Format a number as currency
var n = new Number(42.50);
console.log(n.toLocaleString('en-US', {style: 'currency', currency: 'USD'}));   // $42.50
console.log(n.toLocaleString('en-US', {style: 'currency', currency: 'CAD'}));   // CA$42.50
console.log(n.toLocaleString('en-CA', {style: 'currency', currency: 'CAD'}));   // $42.50
console.log(n.toLocaleString('en-GB', {style: 'currency', currency: 'NOK'}));   // NOK42.50
console.log(n.toLocaleString('nb-NO', {style: 'currency', currency: 'NOK'}));   // kr 42,50
console.log(n.toLocaleString('en-GB', {style: 'currency', currency: 'GBP'}));   // £42.50
console.log(n.toLocaleString('en-GB', {style: 'currency', currency: 'GBP', currencyDisplay: 'name'}));  // 42.50 British pounds sterling
Example #3 – Format a number as percent
console.log(Number(0.37).toLocaleString('en-US', {style: 'percent'}));  // 37%
console.log(Number(0.37).toLocaleString('nb-NO', {style: 'percent'}));  // 37 %
console.log(Number(0.37).toLocaleString('ar-AR', {style: 'percent'}));  // ٣٧٪

External references