JavaScript unshift(): Add Items to the Start of an Array

unshift() adds one or more items to the start of an array and returns the new length. It is useful when you need to prepend items such as priority records, history entries, or the next task in a queue.

Because unshift() modifies the original array, it is often paired with push() and shift() when you want to manage items at both ends of the list. The JavaScript array append guide covers push(), concat(), and spread syntax for the opposite end.

Tested on: Node.js v20.18.2. A short note after each runnable snippet describes what you should see in the console.

Quick reference

Method 1: Add one item to the start with unshift()

unshift mutates the array in place, inserts the new element at index 0, and returns the updated length (not the array).

const colors = ["red", "blue", "green"];
const length = colors.unshift("yellow");

console.log("unshift-array:", colors.join(","));
console.log("unshift-length:", length);

You should see 2 lines, in order: unshift-array: yellow,red,blue,green, unshift-length: 4.

This is the simplest way to prepend a single item to the front of an array. When the original array must remain unchanged, use const next = [item, ...items]; the JavaScript spread operator explains how that syntax expands the existing elements into a new array.

Method 2: Add multiple items with unshift()

You can pass any number of values, and they are inserted in the same order you provide.

const numbers = [3, 4, 5];
numbers.unshift(1, 2);

console.log("unshift-multiple:", numbers.join(","));

You should see one line logging unshift-multiple: 1,2,3,4,5.

This is useful when you want to add a group of items before the current list without rebuilding the full array. For insertion at an arbitrary position rather than strictly index 0, see the broader guide to adding items to a JavaScript array, including splice() and non-mutating alternatives.

Method 3: Prepend mixed values

Arrays in JavaScript can hold strings, numbers, objects, and booleans, so unshift() works with all of them.

const items = [2, { id: 3 }];
items.unshift("start", true);

console.log("unshift-mixed:", JSON.stringify(items));

You should see one line logging unshift-mixed: ["start",true,2,{"id":3}].

Use this pattern when you need to keep a newer item at the front while leaving the rest of the list intact.

Method 4: Combine unshift() with push() and shift()

push() adds to the end, unshift() adds to the start, and shift() removes from the start. That gives you a simple queue or deque-style workflow.

const queue = ["task-2", "task-3"];
queue.unshift("task-1");
queue.push("task-4");
const next = queue.shift();

console.log("queue-state:", queue.join(","));
console.log("queue-shifted:", next);

You should see 2 lines, in order: queue-state: task-2,task-3,task-4, queue-shifted: task-1.

This is the pattern to use when you want to manage a list from both ends in a clear and predictable way. Because an array prepend shifts existing indexes, a JavaScript linked list can be a better model when a large structure needs frequent O(1) insertions at the head.

Summary

JavaScript unshift() is the right choice when you need to prepend one value or several values and keep the rest of the array intact. It returns the new length, works with mixed data, and fits naturally with push() and shift() when you are building queue-like or priority-based array logic. That makes it useful in list management, ordered histories, and small data-processing tasks where the front of the array matters.

Official documentation

• MDN: Array.prototype.unshift()
• MDN: Array.prototype.push()
• MDN: Array.prototype.shift()