Number.
Formats a number the way a given language and region write it: thousands separators, decimal marks, currencies, and percentages.
- Returns
- A string with the number formatted according to the rules of the chosen language.
Example
#const score = 1234567.891
console.log(score.toLocaleString('en-US'))
console.log(score.toLocaleString('de-DE'))
console.log((0.25).toLocaleString('en-US', { style: 'percent' }))Definition and usage
#The toLocaleString() method turns a number into text written the way a given language and region expect. For "en-US", a comma separates thousands and a period separates the decimal part, so 12345.6 becomes "12,345.6". For "de-DE", the same number comes out as "12.345,6", with the periods and commas swapped.
The second argument is an options object, the same one used by Intl.NumberFormat. style: "currency" together with currency: "USD" formats amounts of money, style: "percent" turns 0.25 into "25%", and minimumFractionDigits and maximumFractionDigits set the number of decimal places.
Under the hood, the method creates an Intl.NumberFormat formatter every time it’s called. That doesn’t matter for a single number, but when formatting hundreds of values, such as in a results table, create the formatter once and call its format() method instead. Always pass a language code, because without one the result depends on the user’s browser settings.
Syntax
#number.toLocaleString()
number.toLocaleString(locales)
number.toLocaleString(locales, options)Parameters
#locales
string or array, optional
A language code, such as"en-US","de-DE", or"fr-FR". Omitted, it means the browser’s language.options
object, optional
Settings like inIntl.NumberFormat, includingstyle,currency,minimumFractionDigits, andmaximumFractionDigits.
More examples
#const prices = [49, 1299.5, 15000]
for (const price of prices) {
console.log(price.toLocaleString('en-US', { style: 'currency', currency: 'USD' }))
}Currency formatting always shows two decimal places, even for a whole number like 49, and the comma thousands separator kicks in from four digits onward, as in "$1,299.50" and "$15,000.00".
const average = 4.5
console.log(average.toLocaleString('en-US', { minimumFractionDigits: 2 }))
console.log((3.14159).toLocaleString('en-US', { maximumFractionDigits: 2 }))
console.log(average.toFixed(2))const format = new Intl.NumberFormat('en-US', { maximumFractionDigits: 1 })
const results = [81.66, 95, 70.25]
console.log(results.map((value) => format.format(value)))Browser support
#Widely available
Works in all modern browsers, phones included. You can use it without worry.
- Chrome
- Edge
- Firefox
- Safari
Good practices
#- The result is text for display. Don’t compute with it or store it in a database: keep the raw number, and format it only when showing it.
- The thousands separator in US notation is a plain comma, easy to compare in tests. Some locales use a non-breaking space (
\u00a0) instead, which is worth remembering if you compare output against theirs. - The
maximumFractionDigitsoption rounds the number only for display, the value itself doesn’t change. UnliketoFixed(), it also respects the target locale’s decimal and grouping marks.
Related entries
#- Intl.NumberFormatFormats numbers according to a given language’s rules: separators, currencies, percentages, and units.
- Number.prototype.toFixed()Converts a number into a string with a given number of decimal places.
- Number.prototype.toString()Converts a number into a string, also in a different numeral system, e.g. binary or hexadecimal.
- Math.round()Rounds a number to the nearest integer.
Spotted a mistake or missing an example? Write to us.