Number formatting in JavaScript
Tags: javascript, react, webdev, typescript
Published: 2021-12-02 12:30:43

---
title: 'Number formatting in JavaScript'
published: true
description: "Discover power of 'toLocaleString' functions in JavaScript. Format numbers, currencies, and units without any 3rd party localization library."
tags: ['javascript', 'react', 'webdev', 'typescript']
cover_image: https://simplelocalize.io/blog/number-formatting-in-javascript.jpg
canonical_url: https://simplelocalize.io/blog/posts/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 
```js
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

```js
var exampleNumber = 123456.789;

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

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

### Limit to two significant digits
```js
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.

```js
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.

```js
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`

```js
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.  

```js
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.

```js
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.

```js
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`.

```js
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.

```js
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. 😊
```js
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](https://tc39.es/ecma402)
- [React Localization libraries](/blog/posts/the-most-popular-react-localization-libraries/)

[![react localization](https://simplelocalize.io/assets/cta.jpg)](https://simplelocalize.io)