JavaScript Array unshift() Method

What You’ll Learn

The unshift() method adds one or more elements to the beginning of an array and shifts existing items right. It returns the new length. This tutorial covers syntax, comparison with push(), prepend patterns, and five hands-on examples.

Introduction

Need a new item at the front of a list? A fresh notification, a recent search term, or a priority task? unshift() inserts at index 0 and moves everything else one slot to the right.

It is the mirror of push() (which adds at the end). Like push(), it returns the new array length—not the array itself.

Understanding the unshift() Method

array.unshift(item1, item2, ...) inserts arguments at the start in order: the first argument becomes index 0, the second index 1, and so on. Existing elements shift right to make room.

On large arrays, unshift() can be slower than push() because every element must move. For frequent front inserts at scale, consider a deque structure or prepend with spread when immutability matters.

📝 Syntax

General form of Array.prototype.unshift:

array.unshift(element1, element2, ..., elementN)

Parameters

• element1, element2, ... — values to insert at the beginning.

Return value

• The new length of the array (a number).

Common patterns

• arr.unshift(item) — prepend one element.
• arr.unshift(a, b, c) — prepend multiple in one call.
• arr.unshift(...otherArr) — prepend all items from another array.
• const next = [item, ...arr] — non-mutating prepend.

Examples Gallery

Open DevTools Console (F12) or use Try-it labs. Example N maps to ?tryit=N.

const numbers = [3, 4, 5];

numbers.unshift(1, 2);

console.log(numbers);
// [1, 2, 3, 4, 5]

[1, 2, 3, 4, 5]

const items = ["b", "c"];

const newLength = items.unshift("a");

console.log(newLength);
// 3

console.log(items);
// ["a", "b", "c"]

3
["a", "b", "c"]

const start = [2, 3];
const end = [2, 3];

start.unshift(1);
end.push(1);

console.log("unshift:", start);
// [1, 2, 3]

console.log("push:", end);
// [2, 3, 1]

unshift: [1, 2, 3]
push: [2, 3, 1]

const notifications = ["Older alert", "Previous message"];

notifications.unshift("New message just arrived");

console.log(notifications[0]);
// "New message just arrived"

console.log(notifications);
// ["New message just arrived", "Older alert", "Previous message"]

New message just arrived
["New message just arrived", "Older alert", "Previous message"]

const original = [2, 3, 4];

const updated = [1, ...original];

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

console.log(original);
// [2, 3, 4]  ← unchanged

[1, 2, 3, 4]
[2, 3, 4]

🚀 Common Use Cases

• Notification feeds — newest item at index 0.
• Recent searches — latest query at the top.
• Undo history — prepend latest action (with length cap).
• Priority insertion — urgent task before others.
• Bulk prepend — arr.unshift(...items) in one call.
• FIFO queue — use push + shift, not unshift + pop.

📝 Notes

• Mutates the original array.
• Returns new length, not the array.
• Multiple arguments insert in argument order at the front.
• Slower than push on large arrays (all elements shift).
• Prefer one call with many args over repeated unshift in a loop.
• ES2023: no toUnshifted—use spread for immutable prepend.
• ES3—universal browser support.

💡 Best Practices