The rest parameter syntax allows us to represent an indefinite number of arguments as an array.
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.
Syntax
function f(a, b, ...theArgs) { // ... }
Description
A function's last parameter can be prefixed with ...
which will cause all remaining (user supplied) arguments to be placed within a "standard" JavaScript array.
Only the last parameter can be a "rest parameter".
function myFun(a, b, ...manyMoreArgs) { console.log("a", a) console.log("b", b) console.log("manyMoreArgs", manyMoreArgs) } myFun("one", "two", "three", "four", "five", "six") // Console Output: // a, one // b, two // manyMoreArgs, [three, four, five, six]
Difference between rest parameters and the arguments
object
There are three main differences between rest parameters and the arguments
object:
- rest parameters are only the ones that haven't been given a separate name (i.e. formally defined in function expression), while the
arguments
object contains all arguments passed to the function; - the
arguments
object is not a real array, while rest parameters areArray
instances, meaning methods likesort
,map
,forEach
orpop
can be applied on it directly; - the
arguments
object has additional functionality specific to itself (like thecallee
property).
From arguments to an array
Rest parameters have been introduced to reduce the boilerplate code that was induced by the arguments
// Before rest parameters, "arguments" could be converted to a normal array using: function f(a, b) { let normalArray = Array.prototype.slice.call(arguments) // -- or -- let normalArray = [].slice.call(arguments) // -- or -- let normalArray = Array.from(arguments) let first = normalArray.shift() // OK, gives the first argument let first = arguments.shift() // ERROR (arguments is not a normal array) } // Now, you can easily gain access to a normal array using a rest parameter function f(...args) { let normalArray = args let first = normalArray.shift() // OK, gives the first argument }
Examples
Using rest parameters
In this example, the first argument is mapped to a
and the second to b
, so these named arguments are used as normal.
However, the third argument, manyMoreArgs
, will be an array that contains the 3rd, 4th, 5th, 6th ... nth — as many arguments that the user includes.
function myFun(a, b, ...manyMoreArgs) { console.log("a", a) console.log("b", b) console.log("manyMoreArgs", manyMoreArgs) } myFun("one", "two", "three", "four", "five", "six") // a, one // b, two // manyMoreArgs, [three, four, five, six]
Below... even though there is just one value, the last argument still gets put into an array.
// using the same function definition from example above myFun("one", "two", "three") // a, one // b, two // manyMoreArgs, [three]
Below, the third argument isn't provided, but manyMoreArgs
is still an array (albeit an empty one).
// using the same function definition from example above myFun("one", "two") // a, one // b, two // manyMoreArgs, []
Argument length
Since theArgs
is an array, a count of its elements is given by the length
property:
function fun1(...theArgs) { console.log(theArgs.length) } fun1() // 0 fun1(5) // 1 fun1(5, 6, 7) // 3
Ordinary parameter and rest parameters
In the next example, a rest parameter is used to collect all parameters after the first into an array. Each one of them is then multiplied by the first parameter, and the array is returned:
function multiply(multiplier, ...theArgs) { return theArgs.map(element => { return multiplier * element }) } let arr = multiply(2, 1, 2, 3) console.log(arr) // [2, 4, 6]
Use with the arguments object
Array
methods can be used on rest parameters, but not on the arguments
object:
function sortRestArgs(...theArgs) { let sortedArgs = theArgs.sort() return sortedArgs } console.log(sortRestArgs(5, 3, 7, 1)) // 1, 3, 5, 7 function sortArguments() { let sortedArgs = arguments.sort() return sortedArgs // this will never happen } console.log(sortArguments(5, 3, 7, 1)) // throws a TypeError (arguments.sort is not a function)
To use Array
methods on the arguments
object, it must be converted to a real array first.
function sortArguments() { let args = Array.from(arguments) let sortedArgs = args.sort() return sortedArgs } console.log(sortArguments(5, 3, 7, 1)) // 1, 3, 5, 7
Specifications
Specification |
---|
ECMAScript (ECMA-262) The definition of 'Function Definitions' in that specification. |
Browser compatibility
Desktop | Mobile | Server | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Rest parameters | Chrome Full support 47 | Edge Full support 12 | Firefox Full support 15 | IE No support No | Opera Full support 34 | Safari Full support 10 | WebView Android Full support 47 | Chrome Android Full support 47 | Firefox Android Full support 15 | Opera Android Full support 34 | Safari iOS Full support 10 | Samsung Internet Android Full support 5.0 | nodejs
Full support
6.0.0
|
Destructuring rest parameters | Chrome Full support 49 | Edge Full support 79 | Firefox Full support 52 | IE No support No | Opera Full support 36 | Safari Full support 10 | WebView Android Full support 49 | Chrome Android Full support 49 | Firefox Android Full support 52 | Opera Android Full support 36 | Safari iOS Full support 10 | Samsung Internet Android Full support 5.0 | nodejs Full support Yes |
Legend
- Full support
- Full support
- No support
- No support
- User must explicitly enable this feature.
- User must explicitly enable this feature.