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
Syntax
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 theIntl
main page. options
Optional-
An object with configuration properties. For numbers, see
Number.prototype.toLocaleString()
; for dates, seeDate.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.
Object
:Object.prototype.toLocaleString()
Number
:Number.prototype.toLocaleString()
Date
:Date.prototype.toLocaleString()
Always display the currency for the strings and numbers in the prices
array:
const prices = ["¥7", 500, 8123, 12];
prices.toLocaleString("ja-JP", { style: "currency", currency: "JPY" });
// "¥7,¥500,¥8,123,¥12"
For more examples, see also the Intl.NumberFormat
and Intl.DateTimeFormat
pages.
Using toLocaleString() on sparse arrays
toLocaleString()
treats empty slots the same as undefined
and produces an extra separator:
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
.
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 Language Specification # sec-array.prototype.tolocalestring |
ECMAScript Internationalization API Specification # sup-array.prototype.tolocalestring |
Browser compatibility
BCD tables only load in the browser