Symbol.isConcatSpreadable
The Symbol.isConcatSpreadable
well-known symbol is used to configure if an object should be flattened to its array elements when using the Array.prototype.concat()
method.
Description
The @@isConcatSpreadable
symbol (Symbol.isConcatSpreadable
) 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.
Property attributes of Symbol.isConcatSpreadable |
|
---|---|
Writable | no |
Enumerable | no |
Configurable | no |
Examples
Arrays
By default, Array.prototype.concat()
spreads (flattens) arrays into its result:
let alpha = ['a', 'b', 'c'],
let numeric = [1, 2, 3]
let 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:
let alpha = ['a', 'b', 'c']
let numeric = [1, 2, 3]
numeric[Symbol.isConcatSpreadable] = false
let 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:
let x = [1, 2, 3]
let 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 two properties has to be added.
Specifications
Specification |
---|
ECMAScript Language Specification # sec-symbol.isconcatspreadable |
Browser compatibility
BCD tables only load in the browser