.toLocaleString, one of the most underrated JavaScript features
Tags: javascript, webdev, node
Published: 2022-04-24 06:18:55

`.toLocaleString` and friends are some of the most underrated features of JavaScript. I came over them through a few different wanderings through MDN and I've used them in like every project since.

Here, I'll show you how you can use them in your own code.

## `.toLocaleString` is for formatting

`.toLocaleString` is a method present on dates and numbers, which is used to format them in a locale-specific way.

```javascript
new Date().toLocaleString()
// => 24/4/2022, 10:40:00 am
```

By default, it will use the browser's locale, but you can specify a different one with the `locale` parameter.

```javascript
console.log(new Date().toLocaleString('en-US'))
// => 4/24/2022, 10:40:00 AM
console.log(new Date().toLocaleString('en-GB'))
// => 24/04/2022, 10:40:00
console.log(new Date().toLocaleString('ko-KR'))
// => 2022. 4. 24. Ïò§Ï†Ñ 10:40:49
```

You can further customize the output by specifying the format of the date.

```javascript
console.log(new Date().toLocaleString('en-US', {
	year: 'numeric',
	weekday: 'long',
	month: 'long',
	day: 'numeric',
	hour: 'numeric',
	minute: 'numeric',
	second: 'numeric',
	hour12: false,
}))
// => Sunday, April 24, 2022 at 10:40:00

console.log(new Date().toLocaleString('en-US', {
	dateStyle: 'full',
}))
// => Sunday, April 24, 2022

console.log(new Date().toLocaleString('en-US', {
	dateStyle: 'full',
	timeStyle: 'full',
}))
// => Sunday, April 24, 2022 at 10:40:00 AM India Standard Time

console.log(new Date().toLocaleString('en-US', {
	calendar: 'indian',
}))
// => 2/4/1944 Saka, 10:40:00 AM
// I don't know what that means either

console.log(new Date().toLocaleString('en-US', {
	dayPeriod: 'long',
}))
// => in the morning

console.log(new Date().toLocaleString('en-US', {
	era: 'long',
	dayPeriod: 'long',
	weekday: 'long',
	month: 'long',
	year: 'numeric',
	day: '2-digit',
	hour: '2-digit',
	minute: '2-digit',
	second: '2-digit',
	fractionalSecondDigits: 3,
	timeZoneName: 'long',
}))
// => Sunday, April 24, 2022 Anno Domini at 10:00:00.124 in the morning India Standard Time
```

This totally eliminates the need of date formatting libraries like Moment.js in your code!

### Numbers too!

`.toLocaleString` is also a method present on numbers, which is used to format them in a locale-specific way.

```javascript
console.log(10000000..toLocaleString())
// => 10,000,000
```

As usual, you can specify a different locale with the `locale` parameter.

```javascript
console.log(10000000..toLocaleString('ar-EG'))
// => ١٠٬٠٠٠٬٠٠٠
// Another language I know
```

This one also has options.

```javascript
// currency
10000..toLocaleString('en-US', {style: 'currency', currency: 'USD'})
// => $10,000.00

10000..toLocaleString('en-US', {style: 'currency', currency: 'USD', currencyDisplay: 'name'})
// => 10,000.00 US dollars

(-11.29).toLocaleString('en-US', {style: 'currency', currency: 'USD', currencySign: 'accounting'})
// => ($11.29)

(-11.29).toLocaleString('en-US', {style: 'currency', currency: 'USD', currencySign: 'standard'})
// => -$11.29

// scientific
10000..toLocaleString('en-US', {notation: 'scientific'})
// => 1E4

10000..toLocaleString('en-US', {notation: 'compact'})
// => 10K
1234..toLocaleString('en-US', {notation: 'compact'})
// => 1.2K

1234..toLocaleString('en-US', {notation: 'engineering'})
// => 1.234E3

1234..toLocaleString('en-US', {notation: 'engineering', signDisplay: 'always'})
// => +1.234E3

0.55.toLocaleString('en-US', {style: 'percent'})
// => 55%

1234..toLocaleString('en-US', {style: 'unit', unit: 'liter'})
// => 1,234 L

1234..toLocaleString('en-US', {style: 'unit', unit: 'liter', unitDisplay: 'narrow'})
// => 1,234L
```

Once again, this removes the need for a ton of libraries for number formatting!

---

That was one of the most surprising JavaScript moments for me. Sure, I knew that JavaScript was aware of timezones, but getting access to a whole formatting library? 🤯