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.
The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request.
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 (ECMA-262) The definition of 'Symbol.isconcatspreadable' in that specification. |
Browser compatibility
Desktop | Mobile | Server | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
isConcatSpreadable | Chrome Full support 48 | Edge Full support 15 | Firefox Full support 48 | IE No support No | Opera Full support 35 | Safari Full support 10 | WebView Android Full support 48 | Chrome Android Full support 48 | Firefox Android Full support 48 | Opera Android Full support 35 | Safari iOS Full support 10 | Samsung Internet Android Full support 5.0 | nodejs Full support 6.0.0 |
Legend
- Full support
- Full support
- No support
- No support