Number formatting in JavaScript

Discover the power of toLocaleString() function in JavaScript. Format numbers, currencies, and units without any 3rd party localization library. In simple words, the toLocaleString() method converts a number into a string, using locale format. By default, it uses locale from web browser language, but you can specify it manually.

Syntax

number.toLocaleString(locale, options);

Parameters

• locale (optional) - if not provided, then the method will use the host environment's current locale (e.g., : default browser language)
• options (optional) - object with formatting options

var exampleNumber = 123456.789;

exampleNumber.toLocaleString('pl-PL');
// output: 123.456,789

number.toLocaleString('ar-EG');
// output: ١٢٣٤٥٦٫٧٨٩

Limit to two significant digits

const price = 123456.789;
price.toLocaleString('en-IN', { 
  maximumSignificantDigits: 2 
});
// output: 1,23,000

Use default locale and custom number formatting

Put undefined as first parameter, to use default locale set in browser.

const price = 30000.65;
price.toLocaleString(undefined, { 
  minimumFractionDigits: 2, 
  maximumFractionDigits: 2 
});
// English output: 30,000.65
// German output: 30.000,65
// French output: 30 000,65

Change formatting style

Style property can have 3 different values:

• decimal (default)
• currency
• percent
• unit

In this article, we go through every style.

Style: Currencies

Use style property in options object with value currency to format number into a string.

const price = 123456.789;
price.toLocaleString('de-DE', { style: 'currency', currency: 'EUR' });
// output: 123.456,79 €

price.toLocaleString('ja-JP', { style: 'currency', currency: 'JPY' });
// output: ￥123,457

You can adjust currencyDisplay property to change currency formatting. Possible values are:

• symbol (default)
• code
• name

const price = 123456.789;
price.toLocaleString('de-DE', { 
  style: 'currency', 
  currencyDisplay: 'code', 
  currency: 'EUR' 
});
// output: 123.456,79 EUR

price.toLocaleString('ja-JP', { 
  style: 'currency', 
  currencyDisplay: 'name', 
  currency: 'JPY' 
});
// output: 123,457円

Style: Percentages

Percentage localization is a non-trivial task in some languages. Not in every language, percentage sign comes after a number. For example, in Arabic languages.

const value = 0.767;
value.toLocaleString('pl-PL', { style: 'percent' });
// output: 77%

value.toLocaleString('ar-SA', { style: 'percent' });
// output:؜ ٧٣٪ ؜

Style: Units

Units style is one of the most understated JavaScript locale features. It allows you to format number into any popular units with proper formatting for given locale.

Example with liter unit

Use unit property in options object to set a desired unit.

const value = 3;
value.toLocaleString('pl-PL', {
    style: 'unit',
    unit: 'liter'
});
// output: 3 l

You might also want to adjust unitDisplay property to show full word instead just one letter.

const value = 3;
value.toLocaleString('pl-PL', {
    style: 'unit',
    unit: 'liter',
    unitDisplay: 'long'
});
// output: 3 litry

The shortest version you will get with narrow value in unitDisplay.

const value = 3;
value.toLocaleString('pl-PL', {
    style: 'unit',
    unit: 'liter',
    unitDisplay: 'narrow'
});
// output: 3l

List of JavaScript number locale units

Below, you can check all possible values for unit property.

Kilometer per hour

You can combine two values using per keyword, like X-per-Y. For example, kilometer-per-hour. JavaScript will choose the best-fit localized pattern to format this compound unit.

const speed = 50.2137;
speed.toLocaleString('pt-PT', {
  style: 'unit',
  unit: 'kilometer-per-hour'
});
// output: 50,214 km/h

Terabyte per gram

The unit property doesn't have to make sense, it accepts any combination. 😊

const value = 50.2137;
value.toLocaleString('pl-PL', {
  style: 'unit',
  unit: 'terabyte-per-gram',
  unitDisplay: "long"
});
// output: 50,214 terabajta na gram

Resources:

• tc39.es/ecma402
• React Localization libraries