Array.prototype.toLocaleString()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2017.

The toLocaleString() method of Array instances returns a string representing the elements of the array. The elements are converted to strings using their toLocaleString methods and these strings are separated by a locale-specific string (such as a comma ",").

Try it

const array1 = [1, "a", new Date("21 Dec 1997 14:12:00 UTC")];
const localeString = array1.toLocaleString("en", { timeZone: "UTC" });

console.log(localeString);
// Expected output: "1,a,12/21/1997, 2:12:00 PM",
// This assumes "en" locale and UTC timezone - your results may vary

Syntax

js
toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)

Parameters

locales Optional

A string with a BCP 47 language tag, or an array of such strings. For the general form and interpretation of the locales argument, see the parameter description on the Intl main page.

options Optional

An object with configuration properties. What you can pass here depends on what elements are being converted. For example, for numbers, see Number.prototype.toLocaleString().

Return value

A string representing the elements of the array.

Description

The Array.prototype.toLocaleString method traverses its content, calling the toLocaleString method of every element with the locales and options parameters provided, and concatenates them with an implementation-defined separator (such as a comma ","). Note that the method itself does not consume the two parameters — it only passes them to the toLocaleString() of each element. The choice of the separator string depends on the host's current locale, not the locales parameter.

If an element is undefined, null, it is converted to an empty string instead of the string "null" or "undefined".

When used on sparse arrays, the toLocaleString() method iterates empty slots as if they have the value undefined.

The toLocaleString() method is generic. It only expects the this value to have a length property and integer-keyed properties.

Examples

Using locales and options

The elements of the array are converted to strings using their toLocaleString methods. For example, this snippet implicitly calls the Number.prototype.toLocaleString() method to display the currency for the strings and numbers in the prices array:

js
const prices = ["¥7", 500, 8123, 12];
prices.toLocaleString("ja-JP", { style: "currency", currency: "JPY" });

// "¥7,¥500,¥8,123,¥12"

Using toLocaleString() on sparse arrays

toLocaleString() treats empty slots the same as undefined and produces an extra separator:

js
console.log([1, , 3].toLocaleString()); // '1,,3'

Calling toLocaleString() on non-array objects

The toLocaleString() method reads the length property of this and then accesses each property whose key is a nonnegative integer less than length.

js
const arrayLike = {
  length: 3,
  0: 1,
  1: 2,
  2: 3,
  3: 4, // ignored by toLocaleString() since length is 3
};
console.log(Array.prototype.toLocaleString.call(arrayLike));
// 1,2,3

Specifications

Specification
ECMAScript® 2025 Language Specification
# sec-array.prototype.tolocalestring
ECMAScript® 2025 Internationalization API Specification
# sup-array.prototype.tolocalestring

Browser compatibility

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
toLocaleString
locales parameter
options parameter

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
Has more compatibility info.

See also