JavaScript unshift(): Add Elements at the Beginning

unshift() adds one or more elements to the beginning of a JavaScript array. It mutates the original array, moves existing values to higher indexes, and returns the new length.

const scripts = ["PHP", "ASP", "JavaScript", "HTML"];
const newLength = scripts.unshift("VBScript", "Perl");

console.log(scripts);   // ["VBScript", "Perl", "PHP", "ASP", "JavaScript", "HTML"]
console.log(newLength); // 6

Syntax and return value
Add one value
Add multiple values
Order when unshifting multiple values
How indexes change
Mutation and references
Add an array vs its values
Non-mutating alternatives
Common mistakes

Adding values to the beginning of a JavaScript array with unshift

unshift() Syntax and Return Value Top ↑

array.unshift(element1);
array.unshift(element1, element2, element3);

The return value is the new array length, not the modified array.

Add One Element at the Beginning Top ↑

const languages = ["JavaScript", "Python"];
languages.unshift("PHP");
console.log(languages); // ["PHP", "JavaScript", "Python"]

Add Multiple Elements at the Beginning Top ↑

const values = [4, 5, 6];
values.unshift(1, 2, 3);
console.log(values); // [1, 2, 3, 4, 5, 6]

One unshift() Call vs Repeated Calls Top ↑

Multiple values passed in one call keep their argument order. Repeated single-value calls reverse the order of those newly inserted values.

const first = [4, 5, 6];
first.unshift(1, 2, 3);
console.log(first); // [1, 2, 3, 4, 5, 6]

const second = [4, 5, 6];
second.unshift(1);
second.unshift(2);
second.unshift(3);
console.log(second); // [3, 2, 1, 4, 5, 6]

How unshift() Reindexes Existing Elements Top ↑

The original page demonstrated that numeric keys change when values are inserted at index 0.

const scripts = ["PHP", "ASP", "JavaScript", "HTML"];
scripts.unshift("VBScript", "Perl");

for (const [index, value] of scripts.entries()) {
  console.log(index, value);
}

0 VBScript
1 Perl
2 PHP
3 ASP
4 JavaScript
5 HTML

unshift() Mutates the Original Array Top ↑

const values = [2, 3];
const alias = values;
values.unshift(1);
console.log(alias); // [1, 2, 3]

Add an Array as One Element or Add Its Values Top ↑

const values = [3, 4];
const prefix = [1, 2];

values.unshift(prefix);
console.log(values); // [[1, 2], 3, 4]

Use spread syntax when you want the prefix array's elements inserted individually:

const values = [3, 4];
const prefix = [1, 2];
values.unshift(...prefix);
console.log(values); // [1, 2, 3, 4]

Create a New Array Instead of Mutating Top ↑

const original = [3, 4];
const combined = [1, 2, ...original];

console.log(original); // [3, 4]
console.log(combined); // [1, 2, 3, 4]

Use push() when values should be added to the end, or splice() for a specific position.

Common unshift() Mistakes Top ↑

Describing it as adding to the end; unshift() adds to the beginning.
Assigning array = array.unshift(value) and replacing the array with its length.
Calling unshift() repeatedly and overlooking the reversed insertion order.
Forgetting that existing numeric indexes change.
Expecting unshift(otherArray) to flatten that array.

Add at the End with push() Add at Any Position with splice() Display Array Elements Array Reference

Subhendu Mohapatra

Author & Instructor at plus2net

I write and maintain practical tutorials on Python, PHP, SQL, JavaScript, HTML, jQuery, and web development at plus2net. The tutorials focus on clear explanations, working examples, and code that readers can test and adapt while learning.

About the author Watch on YouTube

Connect: