Discover the power of toLocaleString()
function in JavaScript. Format numbers, currencies, and units without any 3rd party localization library.
In simple words, the toLocaleString()
method converts a number into a string, using locale format. By default, it uses locale from web browser language but you can specify it manually.
Syntax
number.toLocaleString(locale, options);
Parameters
-
locale
(optional) - if not provided, then the method will use the host environment's current locale (e.g.: default browser language) -
options
(optional) - object with formatting options
var exampleNumber = 123456.789;
exampleNumber.toLocaleString('pl-PL');
// output: 123.456,789
number.toLocaleString('ar-EG');
// output: ١٢٣٤٥٦٫٧٨٩
Limit to two significant digits
const price = 123456.789;
price.toLocaleString('en-IN', {
maximumSignificantDigits: 2
});
// output: 1,23,000
Use default locale and custom number formatting
Put undefined
as first parameter, to use default locale set in browser.
const price = 30000.65;
price.toLocaleString(undefined, {
minimumFractionDigits: 2,
maximumFractionDigits: 2
});
// English output: 30,000.65
// German output: 30.000,65
// French output: 30 000,65
Change formatting style
Style property can have 3 different values:
-
decimal
(default) currency
percent
unit
In this article, we go through every style.
Style: Currencies
Use style
property in options object with value currency
to format number into a string.
const price = 123456.789;
price.toLocaleString('de-DE', { style: 'currency', currency: 'EUR' });
// output: 123.456,79 €
price.toLocaleString('ja-JP', { style: 'currency', currency: 'JPY' });
// output: ¥123,457
You can adjust currencyDisplay
property to change currency formatting. Possible values are:
-
symbol
(default) -
code
-
name
const price = 123456.789;
price.toLocaleString('de-DE', {
style: 'currency',
currencyDisplay: 'code',
currency: 'EUR'
});
// output: 123.456,79 EUR
price.toLocaleString('ja-JP', {
style: 'currency',
currencyDisplay: 'name',
currency: 'JPY'
});
// output: 123,457円
Style: Percentages
Percentage localization is a non-trivial task in some languages.
Not in every language, percentage sign comes after a number.
For example, in Arabic languages.
const value = 0.767;
value.toLocaleString('pl-PL', { style: 'percent' });
// output: 77%
value.toLocaleString('ar-SA', { style: 'percent' });
// output: ٧٣٪
Style: Units
Units style is the one of the most understated JavaScript locale features. It allows you format
number into any popular units with proper formatting for given locale.
Example with liter
unit
Use unit
property in options object to set a desired unit.
const value = 3;
value.toLocaleString('pl-PL', {
style: 'unit',
unit: 'liter'
});
// output: 3 l
You might also want to adjust unitDisplay
property to show full word instead just one letter.
const value = 3;
value.toLocaleString('pl-PL', {
style: 'unit',
unit: 'liter',
unitDisplay: 'long'
});
// output: 3 litry
The shortest version you will get with narrow
value in unitDisplay
.
const value = 3;
value.toLocaleString('pl-PL', {
style: 'unit',
unit: 'liter',
unitDisplay: 'narrow'
});
// output: 3l
List of JavaScript number locale units
Below, you can check all possible values for unit
property.
acre
bit
byte
celsius
centimeter
day
degree
fahrenheit
fluid-ounce
foot
gallon
gigabit
gigabyte
gram
hectare
hour
inch
kilobit
kilobyte
kilogram
kilometer
liter
megabit
megabyte
meter
mile
mile-scandinavian
milliliter
millimeter
millisecond
minute
month
ounce
percent
petabyte
pound
second
stone
terabit
terabyte
week
yard
year
Kilometer per hour
You can combine two values using per
keyword, like X-per-Y
. For example kilometer-per-hour
.
JavaScript will choose the best-fit localized pattern to format this compound unit.
const speed = 50.2137;
speed.toLocaleString('pt-PT', {
style: 'unit',
unit: 'kilometer-per-hour'
});
// output: 50,214 km/h
Terabyte per gram
The unit
property doesn't have to make sense, it accepts any combination. 😊
const value = 50.2137;
value.toLocaleString('pl-PL', {
style: 'unit',
unit: 'terabyte-per-gram',
unitDisplay: "long"
});
// output: 50,214 terabajta na gram
Top comments (5)
terabyte-per-gram
could be a useful unit for chemical/biological storage media e.g. DNA 😁wow! that's very useful, interesting :D
I couldn’t find any complete article about this so I wrote one. :D
You did a great job
So much to learn and reference I suppose its a double edged sword as a programmer. Great article though.