.toLocaleString, one of the most underrated JavaScript features

.toLocaleString, one of the most underrated JavaScript features

Siddharth Shyniben's photo
Siddharth Shyniben
·Apr 24, 2022·

3 min read

Table of contents

  • .toLocaleString is for formatting

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

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.

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.

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.

// => 10,000,000

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

// => ١٠٬٠٠٠٬٠٠٠
// Another language I know

This one also has options.

// 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? 🤯

Share this