Definition and Usage

The unshift() function prepends one or more elements to the beginning of an array—similar to inserting items at the front. This also increases the array's length.

This function does not return a new array; instead, it modifies the original array directly.
Additionally, it returns an integer representing the array's new length after the elements have been added.

Basic Example

JavaScript 
const arr = [1, 2, 3];

// Add a single element to the beginning of the array.
arr.unshift(4);
console.log(arr); // Output: [4, 1, 2, 3]


// Add multiple elements to the beginning of the array.
arr.unshift(5, 6, 7);
console.log(arr) // Output: [5, 6, 7, 4, 1, 2, 3]

Syntax

JavaScript 
arr.unshift(element1)
arr.unshift(element1, element2)
arr.unshift(element1, element2, /* …, */ elementN)

arr refers to the array on which the unshift() function is being called.

Parameters

Parameters of the unshift() Function
element1, ..., elementN One or more elements to add to the beginning of the array.
You can specify multiple values to be added in order.

Return Value

The return value represents the total number of elements in the array after the new elements have been added. This value is returned as an integer (e.g., 1, 2, 3, ...).

JavaScript 
const arr = [1, 2, 3];

// Add an element to the beginning of the array and store the return value.
const totalElements = arr.unshift(4);
console.log(totalElements); // Output: 4

Practical Examples

Here are some examples of how to use the unshift() function.

Adding a Single Element

To add a single element to an array, pass the element as an argument to the unshift() function.

JavaScript 
const fruits = ["apple", "banana", "cherry"];

// Add one element to the beginning of the array
fruits.unshift("date");

// Check the contents of the array
console.log(fruits); // Output: ['date', 'apple', 'banana', 'cherry']

Adding Multiple Elements

To add multiple elements to an array, simply pass them as separate arguments to the unshift() function, separated by commas.

JavaScript 
const fruits = ["apple", "banana", "cherry"];

// Add elements to the beginning of the array
fruits.unshift("date", "elderberry");

// Check the contents of the array
console.log(fruits); // Output: ['date', 'elderberry', 'apple', 'banana', 'cherry']

Reversing an Array Using unshift()

You can also use unshift() to reverse the order of elements in an array.

JavaScript 
const numbers = [1, 2, 3, 4, 5];
const reversedNumbers = [];

numbers.forEach(number => {
    reversedNumbers.unshift(number);
});

console.log(reversedNumbers); // Output: [5, 4, 3, 2, 1]

Code Explanation
The forEach() function is used to loop through an array and process each element with a callback function.

  1. First, we define an array called numbers with an initial value of [1, 2, 3, 4, 5].
  2. Next, we create an empty array called reversedNumbers, which will store the elements in reverse order.
  3. We then use the forEach() function to iterate over each element in the numbers array. During each iteration, the current element is assigned to the variable number.
  4. The unshift(number) function is used to insert the current element at the beginning of the reversedNumbers array. This process is repeated for every element, resulting in the elements being added in reverse order.

As a result, the reversedNumbers array ends up containing the elements of numbers in reverse order, which in this case is [5, 4, 3, 2, 1].

When you run this code, you can see that the elements from the original array are added in reverse sequence to the new array. This is one simple way to reverse an array using unshift().

Note!
JavaScript also provides a built-in function called reverse(), which is a simpler and more efficient way to reverse an array.

Specifications

Specification for JavaScript unshift() Function
Specification
unshift() ECMAScript Language Specification
#sec-array.prototype.unshift

Browser compatibility

Browser compatibility for JavaScript unshift() Function
Method
Desktop Chrome
Chrome
DesktopDesktop Edge
Edge
Desktop Firefox
Firefox
Safari
Safari
unshift() 1 12 1 1

References

See also