Apart from being a basic concept of any programming language, JavaScript arrays are ubiquitous and irreplaceable. That's the thing that should be familiar for both an advanced developer and for those who just began their path in learning JS.

There are four main methods that allow you to interact with the array, add or remove some elements from the beginning or from the end of the array. Array.pop(), array.push(), array.shift(), and array.unshift() are those methods. Today, we take a look at the features of array.unshift().

Array.unshift() basics

The Array.unshift(), or unshift(), is interrelated with three other array methods in two ways. There are two scenarios of how we can divide them:

  • By the impact area (the beginning or the end of the array), where shift() and unshift() allow you to interact with the beginning of the array, while push() and pop() with the end, subsequently;

  • By the way it impacts the array (add or remove elements), where push() and unshift() are used for adding an element, and, vice versa, pop() and shift() for removing.

The Array.unshift() method allows you to add an element to the beginning of the array and return the new length of array after inserting an argument. It is evident when you look at the unshift() method itself, as is often the case with JS. Being called or applied, it changes the length of the given array directly.

How to use unshift()?

Despite the use of a shortened name - .unshift() or Array.unshift(), the full name of the method is Array.prototype.unshift(). It can say a lot about the nature of the method: prototype marks that it's built-in JS function, while Array marks how it can be applied.

Syntax:

array.unshift()

Let's see how it works with a simple array containing several elements. Let's begin by adding one element. In our case, we will use a simple array containing several letters. After using the unshift() method, the given element will be moved to the zeroth index, moving all the consecutive elements and shifting their indexes.

let letters = ['c', 'd', 'e', 'f'];
letters.unshift('b');
console.log (letters);
// expected output ['b', 'c', 'd', 'e', 'f']

However, you can add several elements by applying the method instantly. Let's return to the previous example to modify the array by adding two elements simultaneously to create an array starting with the 'a' letter. Please, note that the elements will be added in the same order as they were used as parameters of the method.

let letters = ['c', 'd', 'e', 'f'];
letters.unshift('a', 'b');
console.log(letters);
// expected output ['a', 'b', 'c', 'd', 'e', 'f']

You can apply the method several times using one element each time or apply it once by using several elements. Technically, both ways are correct; however, in case you decide to apply unshift() several times, you should pay special attention to the order in which you will add elements. 

As soon as the method adds a new element every time you apply it, the order of parameters should be inverted. 

let letters = ['c', 'd', 'e', 'f'];
letters.unshift('a', 'b');
console.log(letters);
// expected output ['a' 'b', 'c', 'd', 'e', 'f']
 
let letters = ['c', 'd', 'e', 'f'];
letters.unshift('a');
letters.unshift('b');
console.log(letters);
// expected output ['b', 'a', 'c', 'd', 'e', 'f']
 
let letters = ['c', 'd', 'e', 'f'];
letters.unshift('b');
letters.unshift('a');
console.log(letters);
// expected output ['a', 'b', 'c', 'd', 'e', 'f']

The method also increases the number of elements in the array applied to by the number of elements added.

const numbers = [122, -3, 0]; // the array length is 3
numbers.unshift([-5]); //.unshift changed the length of array to 4
console.log(numbers);
// expected output [[-5], 122, -3, 0]

Although we have used fundamental values (numbers and letters) only, the method can be used to interact with any type of array with any values. Same with the method itself. You can add a number, a string, a boolean, or any other variable you like.

let names = ['Robert', 'James'];
let femaleNames = ['Patricia', 'Mary'];
names.unshift(femaleNames);
// expected output ['Patricia', 'Mary', 'Robert', 'James']

Tips

Although the Array.unshift() method is widely used in JS, it has certain features that distinguish it from other Array methods. The main one is that the unshift() is slightly slower than the push() method, which adds an element to the end of the array. 

Compared to it, unshift() interacts with all the elements inside of the array to change their positions. When you work with basic examples consisting of several lines of code, you will barely feel it. 

Still, when it comes to complex systems, you should think twice before preferring the unshift() to other "more effective" methods to interact with an array. Also, when it comes to the length return of the arrays that do not contain a length property, reflecting the last one in a series of consecutive, zero-based numerical properties may not react correctly.

Compatibility

The unshift() is a fundamental built-in JS function. It is an ECMAScript1 feature, a part of the ES1 (JavaScript 1997). Thus, the unshift() is an ancient function, almost as old as the JavaScript itself. Considering this fact, it is clear that most modern commercial browsers support the ES1 functionality.

Conclusion

The unshift() method is one of the Array.methods(). It's self-evident in the way you should use it, and features you should apprehend are as follows. It allows you to add one or several elements to a front of the array. It overwrites the original array. The applying of the unshift() changes the length of the array, and also returns the new length of the array.