JavaScriptArraysBeginner

Array.unshift()

Adds one or more items to the start of an array (mutates).

Review the syntaxStudy the examplesOpen the coding app
array.unshift(...items)
Open Coding Reference

This static page keeps the syntax and examples indexed for search, while the coding app handles interactive exploration and saved references.

What it does

Overview

Adds one or more items to the start of an array (mutates).

The unshift() method adds one or more elements to the beginning of an array and returns the new length of the array. This method mutates the original array in place. Internally, unshift() is an O(n) operation because it requires the JavaScript engine to re-index every existing element by shifting them to a higher index to make room at the start. For very large arrays, this can be significantly slower than push(), which operates in O(1) time. When multiple arguments are passed to unshift(), they are inserted into the beginning of the array as a single block in the order they appear in the arguments list, preserving their relative sequence.

Quick reference

Syntax

array.unshift(...items)

Inputs

Parameters

itemsany[] · Items to add to the beginning.

See it in practice

Examples

1

Basic Usage with Single and Multiple Elements

var ingredients = ['flour', 'sugar'];
var count = ingredients.unshift('eggs', 'butter');

console.log(count);
console.log(ingredients);
Output:
4 ["eggs", "butter", "flour", "sugar"]

Multiple arguments are prepended to the array in the order provided, and the method returns the updated array length.

2

Using unshift with Spread Syntax

var initialValues = [3, 4];
var valuesToAdd = [1, 2];

initialValues.unshift(...valuesToAdd);
console.log(initialValues);
Output:
[1, 2, 3, 4]

The ES6 spread operator allows prepending an entire array of elements into another array while maintaining the original sequence.

3

Functional Alternative (Non-mutating)

var original = ['b', 'c'];
var newItem = 'a';
var updated = [newItem, ...original];

console.log(original);
console.log(updated);
Output:
["b", "c"] ["a", "b", "c"]

To avoid mutating the original array (as required in Redux or React state updates), use the spread operator within a new array literal instead of unshift().

Debug faster

Common Errors

1

LogicError

Cause: Assuming unshift() returns the modified array for chaining.

Fix: Remember that unshift() returns the new length (a number), not the array reference.

var list = [2, 3].unshift(1).filter(n => n > 0); // TypeError: .filter is not a function (returns 3)
2

PerformanceError

Cause: Using unshift() inside a large loop.

Fix: Push elements to a temporary array and reverse it once, or collect items and use unshift() with spread syntax once at the end.

for (var i = 0; i < 100000; i++) { arr.unshift(i); } // Extremely slow due to constant re-indexing

Runtime support

Compatibility

Node.js, BrowserAll browsersES3+

Source: MDN Web Docs

Common questions

Frequently Asked Questions

Adds one or more items to the start of an array (mutates).

items: Items to add to the beginning.

LogicError: Remember that unshift() returns the new length (a number), not the array reference. PerformanceError: Push elements to a temporary array and reverse it once, or collect items and use unshift() with spread syntax once at the end.