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); // ٥٠٠٬٠٠٠

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

• 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

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