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.
Tested on: Node.js v20.18.2. A short note after each runnable snippet describes what you should see in the console.
Quick reference
| API | Effect |
|---|---|
unshift(...items) |
Insert at index 0, shift others right; returns new length |
push(...items) |
Append at end |
shift() |
Remove first element |
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.
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.
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.
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.
