The unshift() method

JavaScriptJunior~3 min read

unshift() does the opposite of what shift() does: it adds one or more elements to the beginning of an array and returns the array's new length. The method changes (mutates) the original array, and every existing element is shifted to the right onto new indexes.

Theory

TL;DR

unshift() adds elements to the beginning of the array, at index 0.
All existing elements are shifted to the right.
The method mutates the original array.
It returns the new length of the array, not the array itself.
You can pass several values at once, and they keep their order.
Its counterpart: shift() removes an element from the front.

Quick example

javascript

const fruits = ['banana', 'cherry'];
const newLength = fruits.unshift('apple');

console.log(fruits);     // ['apple', 'banana', 'cherry']
console.log(newLength);  // 3

Here 'apple' became the element at index 0, 'banana' moved from 0 to 1, and 'cherry' from 1 to 2. The variable holds the number 3, because the method returns the length, not the array.

Several elements in one call

javascript

const numbers = [3, 4];
numbers.unshift(1, 2);

console.log(numbers); // [1, 2, 3, 4]

The arguments are inserted as a block and in the same order in which they were passed. So unshift(1, 2) is not the same as two consecutive calls unshift(1) and unshift(2): the second variant would give [2, 1, 3, 4].

How it works internally

It makes room at the beginning of the array.
It shifts all current elements onto new indexes.
It inserts the new values at the positions starting from 0.
It updates the length property.

Step 2 is exactly why unshift() is more expensive than push(): appending at the end does not touch any other element's index, while inserting at the front requires rewriting the indexes of the whole array.

Comparison with the other methods

Method	What it does	Where it adds / removes	What it returns	Mutates the array
`push()`	Adds an element	At the end	The new length	Yes
`pop()`	Removes an element	From the end	The removed element	Yes
`unshift()`	Adds an element	At the beginning	The new length	Yes
`shift()`	Removes an element	From the beginning	The removed element	Yes

Usage example: a queue

javascript

const queue = [];

queue.unshift('first');
queue.unshift('second');

console.log(queue); // ['second', 'first']

Each new element lands in front of the previous one, so the oldest value stays at the end of the array. Such a queue is convenient to serve with pop(): you take from the end the item that got there earliest, which gives you FIFO (First In - First Out) behaviour.

In brief

Action	Description
`arr.unshift(value1, value2, ...)`	Adds an element or elements to the beginning
Returns	The new length of the array
Changes the array	Yes
Example	`[2, 3].unshift(1)` gives `[1, 2, 3]`

Bottom line: unshift() is the method for adding elements to the beginning of an array, with an automatic shift of all indexes and an update of the length.

Common mistakes

Assuming the method returns the array. const arr = old.unshift(x) puts a number into arr. To keep working with the array, call unshift() on its own line.
Counting on immutability. unshift() mutates the original array. If you need a new copy, use [newItem, ...arr] or arr.toSpliced(0, 0, newItem).
Mixing up the argument order. unshift(1, 2) gives [1, 2, ...], not [2, 1, ...].
Putting unshift() in a hot loop. Every call reindexes the whole array, so accumulating thousands of elements from the front is noticeably slower than push() followed by reverse().
Using it on "array-like" objects carelessly. On arguments or on a DOM collection the method is only available through Array.prototype.unshift.call(...), and on a live DOM collection it will not work.

Short Answer

Interview ready

Premium

A concise answer to help you respond confidently on this topic during an interview.