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 the one of the most understated JavaScript locale features. It allows you 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.

acre
bit
byte
celsius
centimeter
day
degree
fahrenheit
fluid-ounce
foot
gallon
gigabit
gigabyte
gram
hectare
hour
inch
kilobit
kilobyte
kilogram
kilometer
liter
megabit
megabyte
meter
mile
mile-scandinavian
milliliter
millimeter
millisecond
minute
month
ounce
percent
petabyte
pound
second
stone
terabit
terabyte
week
yard
year

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