By the end of this lesson, you will be able to format JavaScript numbers and dates for different locales using toLocaleString() and common options.
What it is
toLocaleString() is a built-in method on Number and Date objects that returns a string formatted according to a locale and optional formatting rules. Think of it as asking the JavaScript runtime: “How would a person in this locale naturally read this number or date?”
Related terms include locale (such as en-US or de-DE), Intl (the internationalization API), Intl.NumberFormat, and Intl.DateTimeFormat. In practice, toLocaleString() is a convenience wrapper around those formatters.
Why it matters
- It shows numbers with the correct decimal separator, thousands separator, and currency symbol.
- It formats dates and times in a way users expect for their region.
- It reduces manual string building and avoids hard-coded formats like
MM/DD/YYYY. - It helps applications support multiple languages and regions with the same code.
- It improves accessibility and trust by presenting familiar numeric and date patterns.
Syntax or steps
The basic pattern is:
value.toLocaleString(locale, options);For numbers, useful options include style, currency, minimumFractionDigits, maximumFractionDigits, and useGrouping. For dates, useful options include dateStyle, timeStyle, timeZone, weekday, month, day, year, hour, and minute.
If you omit locale, the runtime uses the default locale. If you omit options, it uses a general locale-appropriate format.
Example
const amount = 1234.56;
const date = new Date('2026-01-15T09:30:00Z');
console.log(amount.toLocaleString('en-US', {
style: 'currency',
currency: 'USD'
}));
console.log(amount.toLocaleString('de-DE', {
minimumFractionDigits: 2,
maximumFractionDigits: 2
}));
console.log(date.toLocaleString('en-GB', {
dateStyle: 'medium',
timeStyle: 'short'
}));
console.log(date.toLocaleString('ja-JP', {
timeZone: 'Asia/Tokyo',
dateStyle: 'full'
}));Part by part:
amount.toLocaleString('en-US', { style: 'currency', currency: 'USD' })formats the number as US dollars.amount.toLocaleString('de-DE', { minimumFractionDigits: 2, maximumFractionDigits: 2 })formats the same number using German conventions, such as a comma for the decimal separator.date.toLocaleString('en-GB', { dateStyle: 'medium', timeStyle: 'short' })formats the date and time for British English.date.toLocaleString('ja-JP', { timeZone: 'Asia/Tokyo', dateStyle: 'full' })converts the date to Tokyo time and formats it for Japanese.
Common mistakes
- Assuming the output is fixed. The result depends on the locale and runtime. Do not compare formatted strings for logic; compare the original number or date.
- Forgetting the currency code.
{ style: 'currency' }withoutcurrencythrows an error. Always provide a valid ISO currency code such asUSDorEUR. - Using it on a string.
'1234.5'.toLocaleString()does not format the number. Convert first withNumber()orparseFloat(). - Ignoring time zones. A
Daterepresents an instant, but formatting can shift the displayed time. UsetimeZonewhen the user’s region matters.
When to use it
Use toLocaleString() when you need a quick, readable string for display. Use Intl.NumberFormat or Intl.DateTimeFormat when you need reusable formatters or more control.
| Approach | Best for | Trade-off |
|---|---|---|
toLocaleString() | One-off display formatting | Convenient, but creates a formatter each call |
Intl.NumberFormat / Intl.DateTimeFormat | Repeated formatting or shared options | Slightly more setup, better performance |
| Manual string formatting | Fixed internal formats, such as logs or APIs | Fast, but not locale-aware |
Practice
Guided exercise: Format 9876543.21 as US dollars with two decimal places, then format new Date('2026-03-01T14:00:00Z') for en-GB with medium date and short time.
Challenge: Format 1234567.891 as euros with grouping, and format the same date for Asia/Tokyo using a full date style.
Hint: Use { style: 'currency', currency: 'EUR' } for euros and { timeZone: 'Asia/Tokyo', dateStyle: 'full' } for the date.
Quick check
What does (1234.5).toLocaleString('de-DE') do?
It returns a string formatted using German conventions, typically showing a comma as the decimal separator and a period or space as the grouping separator, depending on the runtime.
Summary
toLocaleString() turns numbers and dates into locale-aware display strings without manual formatting. It is ideal for user-facing output, while Intl formatters are better when you need reusable, high-performance formatting.