XQA
Back to Java
2026-02-056 min read

JS toLocaleString()

Learn JS toLocaleString() step by step with clear examples and exercises.

Title: JavaScript's toLocaleString() Method - A full guide

Why This Matters

In today's globalized world, handling date and number formatting is crucial for creating user-friendly applications that cater to a diverse audience. The toLocaleString() method in JavaScript provides a way to format dates, numbers, and other values according to the user's locale preferences, ensuring a seamless user experience. Understanding this method can help you create more intuitive interfaces and avoid common formatting errors.

Prerequisites

Before diving into the toLocaleString() method, it is essential to have a good understanding of:

  1. JavaScript basics (variables, data types, operators)
  2. Control structures (if-else statements, loops)
  3. Date objects and their methods
  4. Number formatting in JavaScript
  5. Understanding the concept of locale and internationalization (i18n)

Core Concept

The toLocaleString() method is a built-in JavaScript function that formats the specified value according to the current locale's conventions. It can be used with dates, numbers, and other values. This section will delve deeper into the syntax, available options, and common use cases of this powerful method.

Syntax

value.toLocaleString([locale[, options]])
  • value: The value you want to format (e.g., a date object or a number)
  • locale (optional): A string representing the locale to use for formatting. If not provided, the browser's current locale is used.
  • options (optional): An object containing options that customize the formatting behavior.

Available Locale Values

JavaScript supports a wide range of locales, including country codes and language tags. For example:

  • "en-US" (English - United States)
  • "de-DE" (German - Germany)
  • "fr-FR" (French - France)
  • "es-ES" (Spanish - Spain)
  • "zh-CN" (Chinese - China)
  • "ja-JP" (Japanese - Japan)

Options Object

The options object can be used to customize the formatting behavior, such as specifying the currency symbol or date format. The available options are:

  1. style: A string indicating the type of formatting (e.g., "currency", "date", "number", etc.)
  2. currency: A string representing the ISO 4217 currency code to use for currency formatting (optional)
  3. currencyDisplay: A string specifying how the currency symbol should be displayed (e.g., "symbol", "code", or "name")
  4. useGrouping: A boolean indicating whether to use grouping separators for large numbers (defaults to true)
  5. minimumIntegerDigits: An integer specifying the minimum number of digits to display for the integer part of a number (optional)
  6. maximumFractionDigits: An integer specifying the maximum number of digits to display after the decimal point for a number (optional)
  7. timeZone: A string representing the time zone to use for date formatting (defaults to the user's current time zone)
  8. weekday: A string indicating the format for weekdays (e.g., "narrow", "short", or "long")
  9. era: A string specifying whether to include the era name in date formatting (optional)
  10. year: A string indicating the format for the year (e.g., "numeric", "2-digit", or "narrow")
  11. month: A string indicating the format for the month (e.g., "numeric", "2-digit", or "long")
  12. day: A string indicating the format for the day of the month (e.g., "numeric", "2-digit", or "2-digit zero-padded")
  13. hour: A string indicating the format for the hour (e.g., "numeric", "2-digit", or "2-digit zero-padded")
  14. minute: A string indicating the format for the minute (e.g., "numeric", "2-digit", or "2-digit zero-padded")
  15. second: A string indicating the format for the second (e.g., "numeric", "2-digit", or "2-digit zero-padded")
  16. timeZoneName: A string specifying whether to include the time zone name in date formatting (optional)

Examples

  1. Formatting a date using custom options:
let date = new Date();
console.log(date.toLocaleString("en-US", { weekday: "long", year: "numeric", month: "long", day: "numeric" }));
// Output: "Friday, March 24, 2023" (based on the user's locale)
  1. Formatting a number with thousands separators and the Indian Rupee symbol (₹):
let num = 123456.789;
console.log(num.toLocaleString("en-IN", { style: "currency", currency: "INR" }));
// Output: "₹1,23,456.79" (English - India, Indian Rupee format)

Worked Example

Let's create a simple application that formats dates and numbers based on different locales and custom options.

// Create a date object
let date = new Date();

// Format date for various locales with custom options
console.log(date.toLocaleString("en-US", { weekday: "long", year: "numeric", month: "long", day: "numeric" }));
console.log(date.toLocaleString("de-DE", { timeZoneName: "short", hour: "2-digit", minute: "2-digit" }));
console.log(date.toLocaleString("fr-FR", { year: "numeric", month: "long", day: "numeric", weekday: "narrow" }));

// Format number for various locales with custom options
let num = 123456.789;
console.log(num.toLocaleString("en-IN", { style: "currency", currency: "INR" }));
console.log(num.toLocaleString("de-DE", { useGrouping: false, maximumFractionDigits: 2 }));

Common Mistakes

  1. Not providing a locale: If no locale is specified, the browser's current locale will be used. However, this may not always produce the desired output, especially when working with international users.

Solution: Always provide a locale to ensure consistent formatting across different user locations.

  1. Using incorrect options: The options object can be complex and may require careful consideration to achieve the desired formatting. Misconfigured options can lead to unexpected results.

Solution: Study the available options and experiment with them to find the best fit for your application's needs.

  1. Ignoring browser locale: Developers often assume that their own locale is the default one, leading to incorrect formatting when users access the application from other regions.

Solution: Always test your application with different locales to ensure correct formatting for all users.

  1. Not handling invalid or unsupported locales: If you provide an invalid or unsupported locale, the browser will use its default locale for formatting. It is essential to validate and handle such cases gracefully in your application.

Solution: Implement error handling mechanisms to notify users when their selected locale is not supported by the application.

Practice Questions

  1. Write a JavaScript function that formats a date using the "fr-FR" locale (French - France) and returns it as a string, using the "long" format for weekdays, months, and years.
function formatDateFrance(date) {
return date.toLocaleString("fr-FR", { weekday: "long", year: "numeric", month: "long", day: "numeric" });
}
  1. Create a script that formats a number with thousands separators and the Brazilian Real symbol (R$).
function formatNumberBrazil(number) {
return number.toLocaleString("pt-BR", { style: "currency", currency: "BRL" });
}

FAQ

  1. Why can't I use toLocaleString() on primitive values like strings or booleans?
  • JavaScript's toLocaleString() method is designed for formatting complex data types such as dates and numbers. Primitive values like strings and booleans do not have inherent formatting rules, so they cannot be formatted using this method.
  1. How can I customize the date format when using toLocaleString()?
  • You can use the options object to customize the date format. For example, you can specify the order of day, month, and year by setting the options object's timeZone property to "UTC" and its options property to an object containing the desired format properties (e.g., { year: 'numeric', month: 'long', day: '2-digit' }).
  1. What happens if I provide an invalid locale when using toLocaleString()?
  • If you provide an invalid or unsupported locale, the browser will use its default locale for formatting. It is essential to ensure that the provided locale is valid and supported by the user's browser.
  1. Can I format dates and numbers in the same call to toLocaleString()?
  • No, you cannot format both dates and numbers in a single call to toLocaleString(). You must make separate calls for each value you want to format.
  1. Is it possible to use custom number formatting rules with toLocaleString()?
  • While the options object provides several built-in formatting options, it does not allow for complete customization of number formatting rules. For more complex number formatting requirements, consider using libraries such as Intl.js or moment.js.
JS toLocaleString() | Java | XQA Learn