DEV Community

Cover image for Using toLocaleString for number objects in JavaScript
Orim Dominic Adah
Orim Dominic Adah

Posted on • Updated on

Using toLocaleString for number objects in JavaScript

The toLocaleString method in JavaScript is present on the array, date, number object and object data types. This article focuses on the toLocaleString method on JavaScript number objects. Note that toLocaleString doesn't exist in Node.js as at the time of this writing.

The toLocaleString method, when called on a JavaScript number object (not a number literal like 234 or 3, but an identifier - a variable or a constant - with a number value), formats the number based on the values passed into it and returns a string representation of the formatted value. Well, so why not use toString if that's all the toLocaleString method does? Good question!

The toLocaleString method takes in arguments that tell it what human language to format the number object into. In other words, while the Britons will write 'five hundred thousand' as 500,000, the Spaniards will write it as 500.000. The toLocaleString will take the number 500000 and if you ask it to format it for the Britons, it will return '500,000'. If asked to format it for the Spaniards, it will return '500.000'. Everyone will understand the number in their native language. Talk about babel, but for JavaScript numbers to humans. It has support for Arabic too. Now, isn't that awesome?

Okay, talk is cheap. Show me the code.

let num = 500000;
let britishNum = num.toLocaleString("en-GB"); //en-GB: Great Britain English
let numeroEsp = num.toLocaleString("es-ES"); //es-ES: Spanish Spanish
let arabicNum = num.toLocaleString("ar-EG"); //ar-EG: Eastern Arabic
console.log("British representation: ", britishNum); // 500,000
console.log("Spanish representation: ", numeroEsp); // 500.000
console.log("Arabic representation: ", arabicNum); // ٥٠٠٬٠٠٠
Enter fullscreen mode Exit fullscreen mode

Awesome init? Now here's some explanation, and some more toLocaleString awesomeness.

The format or syntax for the implementation of toLocaleString is like this: numObj.toLocaleString([locales [, options]]), where

  • numObj is the number object to be formatted,
  • locales represents a string (like es-ES or ar-EG) which is the language to be formatted into, (See this stackoverflow question for a list of locales codes.)
  • options is an object, with properties that contain some really extra-awesome formatting options, like formatting for currency, how many decimal places do you want ish. The square braces [] only mean that locales and options are optional. In other words, one can use the toLocaleString method without passing them in.

😲 So what language will it be formatted into if one doesn't pass in any parameters? To the default language of your browser of course!.

Now to the really extra-awesomeness part. Talk is cheap you say? Show me the code.

  • Currency formatting
let num = 500000;
let britishCurrency = num.toLocaleString("en-GB", {
  style: "currency",
  currency: "GBP",
let japaneseCurrency = num.toLocaleString("ja-JP", {
  style: "currency",
  currency: "JPY",

console.log("British currency: ", britishCurrency); // £500,000.00
console.log("Japanese currency: ", japaneseCurrency); // ¥500,000
Enter fullscreen mode Exit fullscreen mode
  • Number of decimal places
let num = 500000.5525;
let british = num.toLocaleString("en-GB", {
  maximumFractionDigits: 3,
let spanish = num.toLocaleString("es-ES", {
  maximumFractionDigits: 2,

console.log("British: ", british); // 500,000.553
console.log("Spanish: ", spanish); // 500.000,55
Enter fullscreen mode Exit fullscreen mode

Code shown. Now to the explanation, shall we?

The object passed in after the locales parameter contains properties which one can customise as they please to get the number format that they want. style
currency and
maximumFractionDigits are some of those properties. The object holding those properties is the options parameter in the syntax above.

You can view the MDN Docs on using the options object to customize your toLocaleString output.

Good luck using toLocaleString with number objects!

Cover image by sitepen

Top comments (2)

4esn0k profile image

en-US is not always a default language, it depends on your browser preferences

orimdominic profile image
Orim Dominic Adah

Thank you very much Yaffle. The correction has been made