Skip to main content

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​

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

As shown in the snippet above, unshift() accepts one or more arguments.

In other words, the item1, item2, ..., itemX arguments in the syntax above signify the items you wish to add to the beginning of the calling array.

Let's see precisely how unshift() works with some examples.

Example 1: Use unshift() to 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.

Let's consider another example.

Example 2: Use unshift() to 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().

Overview​

This article discussed what JavaScript's unshift() method does. We also used examples to see how it works.