unshift() JavaScript Array Method – Prepend Items to an Array

Whenever you use unshift() on an array, the method does the following:

1. It adds its arguments to the beginning of its calling array.
2. It returns the calling array’s new length.

Note

• A calling array is an array on which you used unshift(). So, in bestColorsList.unshift(), bestColorsList is the calling array.
• unshift() is sometimes written as Array.prototype.unshift() because it is a method of the Array object’s prototype property.

Syntax of the unshift() Method

unshift() accepts one or more arguments. Here’s the syntax:

callingArray.unshift(item1, item2, ..., itemX)

The item1, item2, ..., itemX arguments signify the items you wish to add to the beginning of the calling array.

Examples of the unshift() Method

Below are examples of the unshift() method.

Add One New Item to the Beginning of an Array

// Define an array:
const numbersArray = [1, 2, 3, 4];

// Add a new item to the beginning of the numbersArray:
numbersArray.unshift(0);

// Check the numbersArray's current content:
console.log(numbersArray);

// The invocation above will return:
[0, 1, 2, 3, 4];

Try it on StackBlitz

The snippet above used unshift() to prepend an item (0) to the beginning of the calling array.

Add Three New Items to the Beginning of an Array

const fruitsArray = ["Mango", "Apple"];
const totalFruits = fruitsArray.unshift("Orange", "Lemon", "Grape");

console.log(fruitsArray);

// The fruitsArray's invocation above will return:
["Orange", "Lemon", "Grape", "Mango", "Apple"];

console.log(totalFruits);

// The totalFruits' invocation above will return: 5

Try it on StackBlitz

In the snippet above, the totalFruits’ invocation returned 5 because unshift() returned the calling array’s new length.

Note

• Use push() or the length property to add new items to the end of an array object.
• You can use JavaScript’s shift() method to remove an array’s first item.
• To remove an array’s last item, use pop().