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.

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

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.

Examples

Arrays

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

JavaScript
var alpha = ['a', 'b', 'c'], 
    numeric = [1, 2, 3]; 

var 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:

JavaScript
var alpha = ['a', 'b', 'c'], 
    numeric = [1, 2, 3]; 

numeric[Symbol.isConcatSpreadable] = false;
var 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:

JavaScript
var x = [1, 2, 3];

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

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

Specifications

Specification Status Comment
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'Symbol.isconcatspreadable' in that specification.
Standard Initial definition.
ECMAScript 2017 Draft (ECMA-262)
The definition of 'Symbol.isconcatspreadable' in that specification.
Draft No change.

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support No support 48 (48) No support No support No support
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support No support No support 48.0 (48) No support No support No support

See also

License

© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/javascript/reference/global_objects/symbol/isconcatspreadable

ECMAScript6 JavaScript Property Symbol