JavaScript Array toLocaleString() Method

What You’ll Learn

The toLocaleString() method turns an array into a comma-separated string, formatting each element for a locale (numbers, dates, currency). It does not change the array. This tutorial covers syntax, options, comparison with toString(), and five examples.

Introduction

When you display prices, dates, or large numbers to users worldwide, raw values like 1234567.89 are hard to read. toLocaleString() formats each array element according to a locale, then joins them with commas—similar to toString(), but locale-aware.

It is read-only: the array stays the same. You get back a string ready for UI labels, alerts, or logging.

Understanding the toLocaleString() Method

array.toLocaleString(locales?, options?) calls toLocaleString on each element (with the same locales and options), then joins the results with a comma (","). Empty slots in sparse arrays are omitted like join.

Under the hood it is like: arr.map(el => el.toLocaleString(locales, options)).join(",") (with spec details for null/undefined).

📝 Syntax

General form of Array.prototype.toLocaleString:

array.toLocaleString(locales, options)

Parameters

• locales (optional) — BCP 47 tag such as "en-US" or "de-DE".
• options (optional) — formatting object passed to each element (e.g. currency for numbers).

Return value

• A string of locale-formatted elements joined by commas.

Common patterns

• arr.toLocaleString() — default locale of the environment.
• arr.toLocaleString("en-US") — US number/date style.
• prices.toLocaleString("en-US", { style: "currency", currency: "USD" })
• dates.toLocaleString("en-GB", { dateStyle: "medium" })
• String(arr) or arr.toString() — non-localized alternative.

Examples Gallery

Open DevTools Console (F12) or use Try-it labs. Example N maps to ?tryit=N. Locale output may vary slightly by browser; examples use explicit locales where shown.

const numbers = [1234.5, 9876543.21];

const text = numbers.toLocaleString("en-US");

console.log(text);
// "1,234.5,9,876,543.21"

1,234.5,9,876,543.21

const numbers = [1234.5, 9876];

const text = numbers.toLocaleString("de-DE");

console.log(text);
// "1.234,5,9.876"

1.234,5,9.876

const prices = [1000, 2500, 99.5];

const text = prices.toLocaleString("en-US", {
  style: "currency",
  currency: "USD"
});

console.log(text);
// "$1,000.00,$2,500.00,$99.50"

$1,000.00,$2,500.00,$99.50

const dates = [
  new Date("2024-06-15T12:00:00Z"),
  new Date("2024-12-25T12:00:00Z")
];

const text = dates.toLocaleString("en-US", { dateStyle: "medium" });

console.log(text);
// e.g. "Jun 15, 2024,Dec 25, 2024"

Jun 15, 2024,Dec 25, 2024

const values = [1234567.89];

console.log(values.toString());
// "1234567.89"

console.log(values.toLocaleString("en-US"));
// "1,234,567.89"

1234567.89
1,234,567.89

🚀 Common Use Cases

• Price lists — format multiple amounts as currency.
• Reports — locale-aware number columns in one string.
• Date ranges — show selected dates for a locale.
• Debug snapshots — quick readable array string in logs.
• Legacy UI — display array contents without manual map.
• Implicit coercion — alert(arr) uses toString, not locale (use explicitly when needed).

📝 Notes

• Does not mutate the array.
• Returns a string, not an array.
• Separator is always comma (no parameter to change it—use map + join).
• Does not translate plain strings.
• null and undefined become empty string segments per spec.
• Objects without toLocaleString fall back to toString.
• For production i18n UI, prefer Intl.NumberFormat / Intl.DateTimeFormat per field.

💡 Best Practices