JavaScript unshift method
last modified April 4, 2025
In this article we show how to add elements to the beginning of an array using
the unshift method in JavaScript.
Array unshift operation
The unshift method adds one or more elements to the beginning of
an array and returns the new length of the array. Unlike concat,
unshift modifies the original array directly.
This method is useful when you need to prepend elements to an existing array.
The unshift method changes the length of the array and shifts all
existing elements to higher indices to make room for the new elements.
The unshift method can take multiple arguments. Each argument
becomes a new element at the start of the array. The elements are added in
the order they are provided to the method.
Basic unshift example
The following example demonstrates the basic usage of the unshift
method.
const fruits = ['banana', 'apple'];
const newLength = fruits.unshift('orange');
console.log(fruits); // Modified original array
console.log(newLength); // New array length
We create an array and add a new element to its beginning. The original array is modified. The method returns the new length of the array.
$ node main.js [ 'orange', 'banana', 'apple' ] 3
Unshifting multiple elements
The unshift method can add multiple elements at once.
const numbers = [3, 4]; const newLength = numbers.unshift(1, 2); console.log(numbers); console.log(newLength);
We add two elements to the beginning of the array. The elements are added in the order they are specified. The method returns the updated array length.
$ node main.js [ 1, 2, 3, 4 ] 4
Unshifting different data types
The unshift() method can handle elements of different data types.
const mixed = [true, {name: 'John'}];
mixed.unshift(42, 'hello', [1, 2]);
console.log(mixed);
We add a number, string, and array to the beginning of an array containing a boolean and an object. JavaScript arrays can hold mixed data types.
$ node main.js
[ 42, 'hello', [ 1, 2 ], true, { name: 'John' } ]
Unshifting to an empty array
The unshift method works with empty arrays.
const empty = [];
const newLength = empty.unshift('first', 'second');
console.log(empty);
console.log(newLength);
When unshifting to an empty array, the elements become the array's contents. The method returns the count of added elements as the new array length.
$ node main.js [ 'first', 'second' ] 2
Performance considerations
The unshift method has O(n) time complexity as it must shift all
existing elements.
const bigArray = new Array(1000000).fill(0);
console.time('unshift');
bigArray.unshift(1);
console.timeEnd('unshift');
This example demonstrates the performance impact of unshifting to a large array. The operation becomes slower as the array size increases due to element shifting.
$ node main.js unshift: 5.234ms
Source
Array unshift - language reference
In this article we have demonstrated how to use the unshift() method to add elements to the beginning of an array in JavaScript.