JavaScript Reference
Array.prototype.unshift()
Add elements to the start of an array. Returns the new length.
Last updated: October 2026
Definition: Array.prototype.unshift() adds one or more elements to the beginning of an array and returns the new length. It mutates the original array by shifting all existing elements to higher indices.
🎬 Live Example
Five unshift patterns. Click any button to see the output.
💡 unshift is O(n) — slower than push for large arrays.
Basic Syntax
array.unshift(element1, element2, ...)
// Returns the new length
// Mutates — re-indexes all existing elementsAdd to the Start
const fruits = ['banana', 'cherry'];
fruits.unshift('apple');
// fruits: ['apple', 'banana', 'cherry']Add Multiple Elements (Order Preserved)
const arr = ['c', 'd'];
arr.unshift('a', 'b');
// arr: ['a', 'b', 'c', 'd']
// They appear in the order you pass them
arr.unshift('x', 'y');
// arr: ['x', 'y', 'a', 'b', 'c', 'd']Return Value Trap
const arr = [2, 3];
const result = arr.unshift(1);
console.log(result); // 3 (new length, not array)
console.log(arr); // [1, 2, 3]
// ❌ Not chainable
arr.unshift(0).push(4); // TypeErrorPerformance Warning
// ❌ O(n²) total — very slow on large arrays
const big = [];
for (let i = 0; i < 10000; i++) {
big.unshift(i); // re-indexes all elements each time
}
// ✅ Reverse + push instead
const big2 = [];
for (let i = 10000; i > 0; i--) {
big2.push(i);
}
// Or build then .reverse()Avoid unshift in hot loops. It's O(n) per call, so building an array of 10K elements via unshift is O(n²) ≈ 100M operations.
Real-World: Newest-First Feed
const feed = [];
function addPost(post) {
feed.unshift(post); // newest first
}
addPost({ id: 1, title: 'First' });
addPost({ id: 2, title: 'Second' });
// feed: [{id:2,...}, {id:1,...}]
// Alternative (faster for many posts):
feed.push(post);
feed.reverse(); // if you need newest first🎯 unshift vs push vs concat vs spread
| Method | Mutates? | Complexity |
|---|---|---|
unshift | Yes | O(n) — slow |
push | Yes | O(1) — fast |
concat | No | O(n) — immutable |
[a, ...b] | No | O(n) — modern |
⚠️ Common Mistakes
- Expecting the array back. unshift returns the new length.
- Using unshift in loops. O(n²) performance — terrible on large arrays.
- Chaining unshift().push(). Throws TypeError.
- React state mutation. Use
[newItem, ...state]instead. - Confusing argument order.
unshift(a, b)puts a first, then b. - Assuming it deduplicates. It doesn't — check with
includesfirst.
❓ Frequently Asked Questions
What does Array.unshift() do in JavaScript?
Array.unshift() adds one or more elements to the beginning of an array and returns the new length. It mutates the original array and shifts existing elements to higher indices.
Does unshift return the new array?
No. unshift returns the new length (a number), not the array. This makes it non-chainable with other array methods.
What is the difference between unshift and push?
unshift adds to the beginning (O(n) — slow, re-indexes all elements). push adds to the end (O(1) — fast). Both mutate and return the new length.
Is unshift slower than push?
Yes. unshift is O(n) because every existing element must be shifted up by one index. push is O(1). For large arrays, avoid unshift in hot loops.
How do I add multiple elements at the start?
unshift accepts multiple arguments: arr.unshift(a, b, c) adds three elements to the front in that order. The final array starts with a, then b, then c.