Array unshift Method is the Javascript method that adds one or more elements to the beginning of an array and returns the new length of the array. This article will look closely at what the unshift method does, how it works, etc. We will learn how to add a single element or multiple items to an existing array, learn How to merge two arrays using the Unshift method, etc.
Table of Contents
Array unshift Method
The array Unshift method is a built-in JavaScript method that adds new elements to the beginning of an array. It takes the element to be added as an argument and returns the array’s new length. This method can insert scalar values, objects, or another array into an array.
Syntax
The syntax for the unshift() method is as follows:
1 2 3 4 5 | array.unshift(element0) array.unshift(element0, element1) array.unshift(element0, element1, /* … ,*/ elementN) |
Here, the array is the array to which we want to add elements, and element1, element2, …, and elementN are the elements we want to add to the beginning of the array. Note that this method can add as many elements as we want.
Array unshift Examples
Let us look at some of the examples of the array unshift method.
Adding an item to the array
The code snippet that follows creates an array of numbers with four items. It then uses the unshift method to insert 1 to the beginning of the array.
1 2 3 4 5 6 | let numbers=[2,3,4,5] numbers.unshift(1) //inserting 1 at the start of numbers array console.log(numbers) //[ 1, 2, 3, 4, 5 ] |
Adding multiple items to the array
You can insert multiple elements to the array by supplying multiple items separated by a comma to the unshift method.
1 2 3 4 5 6 7 8 | let numbers=[5,6,7] //inserting multiple items at the start of numbers array numbers.unshift(1,2,3,4) console.log(numbers) //[ 1, 2, 3, 4, 5, 6, 7 ] |
Merging arrays using unshift method
We can use unshift method to merge two arrays. The code below merges the nums array with the numbers array.
Note that we are not creating a new array but taking the value from the nums array and inserting it at the start of the numbers array.
1 2 3 4 5 6 7 8 | let numbers=[11,12,13,14] let nums=[1,2,3,4] numbers.unshift(...nums) //pushing nums array to numbers console.log(numbers) //[ 1, 2, 3, 4, 11, 12, 13, 14 ] |
The unshift method mutates the array
The unshift method mutates the array. It changes the length and content of the current array.
If you do not want to mutate the array (i.e., you want to return a new one instead of modifying the array), then you can use the concat method or the spread operator.
The following code uses the spread operator to insert a new value at the beginning of the array without modifying the original array.
1 2 3 4 5 6 | let numArr = [1, 2, 3]; let newArr = [4, ...numArr]; console.log(numArr); // Output: [1, 2, 3] console.log(newArr); // Output: [ 4, 1, 2, 3 ] |
The following code uses the concat method to create a new array and insert a value 4 at the beginning of the array
1 2 3 4 5 6 | let numArr = [1, 2, 3]; let newArr = [4].concat(numArr); console.log(numArr); // Output: [1, 2, 3] console.log(newArr); // Output: [ 4, 1, 2, 3 ] |
Vs. push
The push method is very similar to the unshift method. The difference between push & unshift is that the push method appends an element to the end of an array, while the unshift method inserts an element at the start of an array.
The following code uses the push method to push a value into the array. Note that it will insert the value at the end of the array.
1 2 3 4 5 | let numArr = [1, 2, 3]; numArr.push(4) console.log(numArr); // Output: [ 1, 2, 3, 4 ] |
Performance of unshift method
When we call unshift() on an array, it has to shift existing elements to a higher index to make room for the new elements.
Shifting elements is a time-consuming process. Its performance depends on the size of the array and the number of elements it will be moving. It also needs to assign a new index number to every element in the array.
Hence if you are working on a large array and do a unshift regularly, you need to rethink your data structure.
The push method is much faster than the unshift as it does not have to move the elements and assign a new index to them.
Array Like objects
The unshift is a generic method and will work on the array-like objects.
The code below applies the unshift method on an array-like object using the call function. As you can see, we insert value 1 at index 0 and push all the other numeric properties one index higher.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | const arrayLike = { 0: 0, 1: 1, 2: 2, length: 3, unrelated: "foo", }; let removedItem = Array.prototype.unshift.call(arrayLike,1); console.log(removedItem) // 4 console.log(arrayLike); //{ '0': 1, '1': 0, '2': 1, '3': 2, length: 4, unrelated: 'foo' } |
Summary
- The array unshift method inserts an element (or elements) to the beginning of an Array.
- The unshift method alters the original array. It changes its length and content. It returns the new length of the array
- You can insert a single item or multiple items or merge two or more arrays.
- Unshift is slower as it needs to move the entire array to make space for new elements.
