Intl.
Formats numbers according to a given language’s rules: separators, currencies, percentages, and units.
- Returns
- A formatter object with a
format()method (andformatToParts()).
Example
#const price = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' })
console.log(price.format(49))
console.log(price.format(1299.5))
console.log(new Intl.NumberFormat('en-US').format(1234567.891))Definition and usage
#Intl.NumberFormat is a built-in number formatter that knows the writing conventions of different languages and countries. In the US, a period separates the decimal part and a comma separates thousands, while in Germany it’s the other way around: a comma for the decimal part and a period for thousands. Instead of writing this by hand, you create a formatter for the chosen locale and call its format() method.
The style option sets the kind of number: "decimal" (the default), "currency" for amounts of money (needs a currency, e.g. currency: "USD"), "percent" for percentages (the value 0.85 gives "85%"), and "unit" for units of measure. The minimumFractionDigits and maximumFractionDigits options set the number of decimal places, and notation: "compact" shortens large numbers, e.g. to "1.5K".
Creating a formatter costs a little, so if you’re formatting many numbers, create it once and reuse it. For one-off use, the shorter toLocaleString() number method is enough, and it accepts the same options.
Syntax
#new Intl.NumberFormat(locales)
new Intl.NumberFormat(locales, options)
formatter.format(number)Parameters
#locales
optional, string or array
A locale code, e.g."en-US","de-DE", or"pl-PL". If omitted, it means the browser’s language.options
optional object
Settings, includingstyle,currency,unit,minimumFractionDigits,maximumFractionDigits, andnotation.
More examples
#const percent = new Intl.NumberFormat('en-US', { style: 'percent' })
const twoDigits = new Intl.NumberFormat('en-US', {
minimumFractionDigits: 2,
maximumFractionDigits: 2
})
console.log(percent.format(0.85))
console.log(twoDigits.format(3.14159))
console.log(twoDigits.format(7))const amount = 1234.5
console.log(new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(amount))
console.log(new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format(amount))
console.log(amount.toLocaleString('en-GB', { style: 'currency', currency: 'GBP' }))const compact = new Intl.NumberFormat('en-US', { notation: 'compact' })
console.log(compact.format(1500))
console.log(compact.format(2500000))Browser support
#Widely available
Works in all modern browsers, phones included. You can use it without worry.
- Chrome
- Edge
- Firefox
- Safari
Good practices
#- Grouping and decimal marks aren’t universal. German swaps the comma and period compared to English, so don’t hardcode a separator, let
Intl.NumberFormathandle it for the target locale. - The formatter inserts non-breaking spaces (
\u00a0) in some locales instead of regular ones. When comparing formatter output in tests, compare it against the same formatter’s result, or account for that character. - Create the formatter once, outside the loop, and reuse it. For a single number,
number.toLocaleString("en-US")is enough.
Related entries
#- Intl.DateTimeFormatFormats dates and times according to the rules of a chosen language and time zone.
- Number.prototype.toFixed()Converts a number into a string with a given number of decimal places.
- Math.round()Rounds a number to the nearest integer.
- DateAn object representing a specific moment in time, with methods to read and change the date and time.
- Number.prototype.toLocaleString()Formats a number the way a given language and region write it: thousands separators, decimal marks, currencies, and percentages.
- Intl.PluralRulesPicks the correct grammatical category for a number in a given language, such as one, few, or many.
Spotted a mistake or missing an example? Write to us.