Rest Parameters
Learn how rest parameters collect the remaining arguments passed to a function into a real array, how they compare to the old arguments object, and how they contrast with the spread operator.
Reading Time
12 min
Lesson
Lesson 25 of 48
Introduction
In the previous lesson, the spread operator used ... to expand a collection out into individual values. Rest parameters use the exact same three dots, but for the opposite purpose: instead of expanding values outward, rest gathers many individual values back together into a single array. When ... appears in a function's parameter list, it collects every remaining argument the function was called with into one real array.
Basic Rest Parameters Example
Console Output
Click “Run” to see the console output here.
Contrast with the Old arguments Object
Before rest parameters existed, every regular function had access to an implicit, array-like object called arguments, which held every argument passed to the call. It worked, but it had real downsides: arguments is not a true array, so methods like .map(), .filter(), and .reduce() aren't available on it directly without first converting it (for example with Array.from(arguments)). It also doesn't exist at all inside arrow functions, and it always contains every argument, with no way to grab "just the extra ones" the way rest parameters can.
arguments vs. Rest Parameters Example
Console Output
Click “Run” to see the console output here.
Rest Parameters Must Come Last
A rest parameter collects everything remaining, so by definition it can only make sense as the very last parameter in a function's parameter list. JavaScript enforces this with a SyntaxError if you try to place anything after it — there's nothing left for another named parameter to receive once the rest parameter has claimed the remainder of the arguments.
Rest Must Be Last Example
Console Output
Click “Run” to see the console output here.
Combining Rest with Named Parameters
Rest parameters are frequently combined with one or more regular named parameters that come before them. The named parameters capture specific, expected values, while the rest parameter scoops up whatever is left — however many extra arguments that turns out to be, including zero.
Combining with Named Parameters Example
Console Output
Click “Run” to see the console output here.
Rest in Destructuring: Arrays and Objects
The rest pattern also appears in destructuring, which you covered in the last two lessons — a rest element in an array destructuring pattern collects the remaining elements into a new array, and a rest property in an object destructuring pattern collects the remaining properties into a new object. This is a different context from rest parameters in a function signature, but the same underlying idea: collect what's left over.
Rest in Destructuring Example
Console Output
Click “Run” to see the console output here.
Rest vs. Spread: Opposite Operations, Same Syntax
It's worth stating this plainly, since it trips up a lot of learners: rest and spread look identical — both are written as ... — but they do opposite things, and which one you're looking at depends entirely on where the ... appears. In a destructuring pattern or a function's parameter list, ... gathers values together (rest). In an array literal, object literal, or function call's argument list, ... expands a collection outward into individual values (spread). Same punctuation, opposite direction.
Rest vs. Spread Side by Side
Console Output
Click “Run” to see the console output here.
Rest vs. Spread at a Glance
| Rest (...) | Spread (...) | |
|---|---|---|
| Direction | Gathers values together | Expands values apart |
| Where it appears | Function parameters, destructuring patterns | Array/object literals, function call arguments |
| Result | A single new array or object | Individual elements or properties |
| Example | function f(...args) {} | f(...argsArray) |
A Quick Way to Tell Them Apart
If the ... appears where a value is being defined or declared (a parameter list, or the left side of a destructuring assignment), it's rest — it's collecting things. If it appears where a value is being used or passed (inside [], {}, or a function call's parentheses), it's spread — it's expanding things.
Only One Rest Parameter Per Function
A function can have only a single rest parameter, and again, it must be the last one. You also can't give a rest parameter a default value the way you can with a regular parameter, since it's already guaranteed to be an array (possibly empty) rather than possibly undefined — there's nothing for a default to protect against.