Spread operator

The spread syntax allows an expression to be expanded in places where multiple arguments (for function calls) or multiple elements (for array literals) or multiple variables (for destructuring assignment) are expected.

Syntax

For function calls:

myFunction(...iterableObj);

For array literals:

[...iterableObj, 4, 5, 6];

Examples

A better apply

Example: it is common to use Function.prototype.apply in cases where you want to use an array as arguments to a function.

function myFunction(x, y, z) { }
var args = [0, 1, 2];
myFunction.apply(null, args);

With ES2015 spread you can now write the above as:

function myFunction(x, y, z) { }
var args = [0, 1, 2];
myFunction(...args);

Any argument in the argument list can use the spread syntax and it can be used multiple times.

function myFunction(v, w, x, y, z) { }
var args = [0, 1];
myFunction(-1, ...args, 2, ...[3]);

A more powerful array literal

Example: Without ES2015 spread, if you have an array and want to create a new array with the existing one being part of it, the array literal syntax is no longer sufficient and you have to fall back to imperative code, using a combination of push, splice, concat, etc. With spread syntax this becomes much more succinct:

var parts = ['shoulders', 'knees']; 
var lyrics = ['head', ...parts, 'and', 'toes']; 
// ["head", "shoulders", "knees", "and", "toes"]

Just like with spread for argument lists ... can be used anywhere in the array literal and it can be used multiple times.

Apply for new

Example: In ES5 it is not possible to compose new with apply. (In ES5 terms, apply does a [[Call]] and not a [[Construct]].) In ES2015 the spread syntax naturally supports this:

var dateFields = readDateFields(database);
var d = new Date(...dateFields);

Copy an array

var arr = [1, 2, 3];
var arr2 = [...arr]; // like arr.slice()
arr2.push(4); 

// arr2 becomes [1, 2, 3, 4]
// arr remains unaffected

Note: Typically the spread operators in ES2015 goes one level deep while copying an array. Therefore, they are unsuitable for copying multidimensional arrays. It's the same case with Object.assign() and Object spread operators. Look at the example below for a better understanding.

var a = [[1], [2], [3]];
var b = [...a];
b.shift().shift();// a is now [[], [2], [3]]

A better way to concatenate arrays

Example: concat is often used to concatenate an array to the end of an existing array. In ES5 this is done as:

var arr1 = [0, 1, 2];
var arr2 = [3, 4, 5];
// Append all items from arr2 onto arr1
arr1.concat(arr2);

In ES2015 with spread this becomes:

var arr1 = [0, 1, 2];
var arr2 = [3, 4, 5];
arr1 = [...arr1, ...arr2];

Example: unshift is often used to insert values in an array at the start of an existing array. In ES5 this is done as:

var arr1 = [0, 1, 2];
var arr2 = [3, 4, 5];
// Prepend all items from arr2 onto arr1
Array.prototype.unshift.apply(arr1, arr2)

In ES2015 with spread this becomes:

var arr1 = [4, 5, 6];
var arr2 = [1, 2, 3];
arr1 = [...arr2, ...arr1]; // arr1 is now [1, 2, 3, 4, 5, 6]

Only for iterables

Note that the spread operator can be applied only to iterable objects:

var obj = {'key1': 'value1'};
var array = [...obj]; // TypeError: obj is not iterable

Rest operator

Rest operator looks exactly like the spread syntax, and is used for destructuring arrays and objects. In a way, Rest elements are the opposite of spread elements - spread elements 'expands' an array into its elements, and rest elements collects multiple elements and 'condenses' into a single element. See rest parameters.

Specifications

Specification	Status	Comment
ECMAScript 2015 (6th Edition, ECMA-262)	Standard	Defined in several sections of the specification: Array Initializer, Argument Lists
ECMAScript 2017 Draft (ECMA-262)	Draft	No changes.

Browser compatibility

See also

• Rest parameters