Array.prototype.unshift()
Adds one or more elements to the beginning of an array and returns the array's new length.
unshift()
unshift(element1)
unshift(element1, element2)
unshift(element1, element2, /* …, */ elementN)- Added in JavaScript ES3
Parameters
| Parameter | Type | Description |
|---|---|---|
$element1, …, elementNoptional | any | The elements to add to the front of the array. Multiple elements are inserted as a chunk, in the same order they were passed. |
Return value
numberThe new length property of the object upon which the method was called.
Errors
Throws a TypeError if the resulting length would exceed 2^53 - 1, or when called on a frozen array in strict mode.
Changelog
- PHP ES3Introduced on Array.prototype.
- PHP ES2015Length handling was specified up to 2^53 - 1.
unshift() inserts elements at the front of an array, shifting everything else up, and returns the new length. It is the mirror of push() and the counterpart to shift().
When to reach for it
Use it for newest-first lists — a notification feed, a recent-files list, a log where the latest entry belongs at the top. It also prepends a default or sentinel value onto a parsed list in one call.
What trips people up
The order rule for multiple arguments catches almost everyone. unshift(1, 2, 3) inserts the chunk in the order given, producing [1, 2, 3, …]. Calling unshift three times with one argument each produces [3, 2, 1, …], because each call goes in front of the previous one. One call is not equivalent to a loop.
Like shift(), it must reindex every existing element, so it is O(n); building a list by repeatedly unshifting is quadratic. The usual alternative is to push() and then reverse() once, or to build with spread: [newItem, ...list], which also avoids mutating a shared array. And as with push(), the return value is a number, so it cannot be chained.
Example
When to use it
- Prepend the newest notification to a feed rendered newest-first
- Insert a default option at the top of a select list
- Add a sentinel or header value in front of parsed data
- Push an item to the front of a priority queue
Frequently asked questions
What does unshift() return?
It returns the new length of the array as a number, not the array, so unshift() calls cannot be chained.
Why is unshift() in a loop giving reversed results?
Each call inserts in front of what the previous call added, so looping reverses the order; pass all elements to a single unshift() call to keep them in sequence.
Is unshift() slower than push()?
Yes. unshift() has to move every existing element up one index, making it O(n), while push() writes at the end in constant time.
More examples
Newest-first feed with a cap
Each new notice goes to the front while pop() drops the oldest once the cap is exceeded. The combination keeps a fixed-size, newest-first window.
const feed = ["older", "oldest"];
function addNotice(text) {
feed.unshift(text);
if (feed.length > 3) feed.pop();
return feed;
}
console.log(addNotice("newer")); // ['newer','older','oldest']
console.log(addNotice("newest")); // ['newest','newer','older']Non-mutating prepend with spread
Spread builds a new array and leaves the source intact, which is what shared state and function arguments need. unshift() gives the same contents but rewrites the original array.
const original = [2, 3];
const next = [1, ...original];
console.log(next); // [1,2,3]
console.log(original); // [2,3] — untouched
const mutated = [2, 3];
mutated.unshift(1);
console.log(mutated); // [1,2,3] — same result, source changedWhy repeated unshift is slow
Both loops produce the same reversed array, but the first moves every existing element on each iteration. Pushing and reversing once does the same work in linear time.
const source = [1, 2, 3, 4, 5];
// Quadratic: every unshift reindexes the whole array.
const slow = [];
for (const v of source) slow.unshift(v);
console.log(slow); // [5,4,3,2,1]
// Linear: push then reverse once.
const fast = [];
for (const v of source) fast.push(v);
fast.reverse();
console.log(fast); // [5,4,3,2,1]
Discussion