DEV Community

Cover image for .toLocaleString, one of the most underrated JavaScript features
Siddharth
Siddharth

Posted on • Originally published at blog.siddu.tech

.toLocaleString, one of the most underrated JavaScript features

.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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

console.log(10000000..toLocaleString())
// => 10,000,000
Enter fullscreen mode Exit fullscreen mode

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

console.log(10000000..toLocaleString('ar-EG'))
// => ١٠٬٠٠٠٬٠٠٠
// Another language I know
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

Discussion (28)

Collapse
joelbonetr profile image
JoelBonetR

Not only in JS, there are bugs in some games due to forgetting about this when dealing with dates in C# in Unity and so on 😆

Collapse
siddharthshyniben profile image
Siddharth Author

Haha, dates are a pain

Collapse
birki profile image
Marcel Birkenkamp

Blain is a Pain

Thread Thread
joelbonetr profile image
JoelBonetR • Edited on

No Pain no Blain 💪🏼😂

Collapse
eziyadah profile image
Eiyad Z.

I have used it for dates before, but really didn’t realize that I can do all of this ☺️

Great Article! 👏🏻👏🏻

Collapse
yukimyona profile image
Oluwapelumi Odumosu • Edited on

My mind is blown, I've used it a ton of times for date formatting but didn't even know it had some more properties for dates! And that it can also be used for numbers 🤯.
I'm definitely trying this out.
Thanks for this piece.

Collapse
busyxiang profile image
busyxiang

Didn't even realise you can do all this, thank you for the sharing

Collapse
venkatesanmca008 profile image
venkatesanmca008

good one ..

Collapse
ricky11 profile image
Rishi U

awesome, why the .. for some items and not others?

Collapse
siddharthshyniben profile image
Siddharth Author

In JavaScript, you can directly acess properties on numbers. You can either use 2 dots or braces instead

10.toString() // error
(10).toString() // ok
10..toString() // ok
Enter fullscreen mode Exit fullscreen mode
Collapse
triyanox profile image
Mohamed Achaq

I'm using this feature a lot when displaying dates !

Collapse
augustoapg profile image
Augusto Peres

MIND BLOWN! I’ll use it for sure!! Thanks!!

Collapse
arunagnihotri profile image
Arun Agnihotri

I used it for dates only but very basic only. Didn't know all this was possible.
Thanks Siddharth!!

Collapse
frodolight profile image
Frodo

Thank you.

Collapse
thomasbnt profile image
Thomas Bnt

Good post and useful feature 👌

Collapse
siddharthshyniben profile image
Siddharth Author

Thanks!

Collapse
elainedelgado profile image
Elaine Delgado

Thanks, that helped a lot!!
Goodbye libraries for number formatting! =D

Collapse
yashdesai profile image
Yash Desai

Thanks for sharing 👍

Collapse
onedamianocoder profile image
onedamianocoder

clear explanation ! :)

Collapse
amircahyadi profile image
Amir-cahyadi

Nice 👍

Collapse
mat3uszkek profile image
Mateusz Skrobiś

I didn't know about that - WOW! this is awesome :) thank u very much for this article!

Collapse
jofwitsolution profile image
Faleye Oluwafemi Joseph

Exactly what I need at the moment. Thank you so much.

Collapse
siddharthshyniben profile image
Siddharth Author

Was that pun intended 🤣

Collapse
lioness100 profile image
Lioness100

What are the differences between Number#toString() and Intl.NumberFormat?

Collapse
siddharthshyniben profile image
Siddharth Author

.toString doesn't provide the features of Intl. It only supports stringifying to a base.

Collapse
lioness100 profile image
Lioness100 • Edited on

Sorry, I meant .toLocaleString()

Thread Thread
siddharthshyniben profile image
Siddharth Author

The features are the same, except Intl is faster when you need to run the stringification multiple times

Thread Thread
lioness100 profile image
Lioness100

Ah, thanks!