Symbol.isConcatSpreadable

Baseline Widely available

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

The Symbol.isConcatSpreadable static data property represents the well-known symbol Symbol.isConcatSpreadable. The Array.prototype.concat() method looks up this symbol on each object being concatenated to determine if it should be treated as an array-like object and flattened to its array elements.

Try it

const alpha = ["a", "b", "c"];
const numeric = [1, 2, 3];
let alphaNumeric = alpha.concat(numeric);

console.log(alphaNumeric);
// Expected output: Array ["a", "b", "c", 1, 2, 3]

numeric[Symbol.isConcatSpreadable] = false;
alphaNumeric = alpha.concat(numeric);

console.log(alphaNumeric);
// Expected output: Array ["a", "b", "c", Array [1, 2, 3]]

Value

The well-known symbol Symbol.isConcatSpreadable.

Property attributes of `Symbol.isConcatSpreadable`
Writable	no
Enumerable	no
Configurable	no

Description

The [Symbol.isConcatSpreadable] property can be defined as an own or inherited property and its value is a boolean. It can control behavior for arrays and array-like objects:

For array objects, the default behavior is to spread (flatten) elements. Symbol.isConcatSpreadable can avoid flattening in these cases.
For array-like objects, the default behavior is no spreading or flattening. Symbol.isConcatSpreadable can force flattening in these cases.

Examples

Arrays

By default, Array.prototype.concat() spreads (flattens) arrays into its result:

const alpha = ["a", "b", "c"];
const numeric = [1, 2, 3];

const alphaNumeric = alpha.concat(numeric);

console.log(alphaNumeric); // Result: ['a', 'b', 'c', 1, 2, 3]

When setting Symbol.isConcatSpreadable to false, you can disable the default behavior:

const alpha = ["a", "b", "c"];
const numeric = [1, 2, 3];

numeric[Symbol.isConcatSpreadable] = false;
const alphaNumeric = alpha.concat(numeric);

console.log(alphaNumeric); // Result: ['a', 'b', 'c', [1, 2, 3] ]

Array-like objects

For array-like objects, the default is to not spread. Symbol.isConcatSpreadable needs to be set to true in order to get a flattened array:

const x = [1, 2, 3];

const fakeArray = {
  [Symbol.isConcatSpreadable]: true,
  length: 2,
  0: "hello",
  1: "world",
};

x.concat(fakeArray); // [1, 2, 3, "hello", "world"]

Note: The length property is used to control the number of object properties to be added. In the above example, length:2 indicates that two properties have to be added.

Specifications

Specification
ECMAScript® 2027 Language Specification # sec-symbol.isconcatspreadable

Browser compatibility

	Desktop					Mobile							Server
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox for Android	Opera Android	Safari on iOS	Samsung Internet	WebView Android	WebView on iOS	Bun	Deno	Node.js
`isConcatSpreadable`	48	15	48	35	10	48	48	35	10	5.0	48	10	1.0.0	1.0	6.0.0