JavaScript Array unshift() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Array
Decorative image with the word UNSHIFT

Definition

Array.prototype.unshift(...items) inserts one or more values at the start of an array, shifts existing indexes up, grows length, and returns the new length (not the array). It mutates in place — the pair of shift().

Remember
array.unshift(item1, item2, …)

adds to the start
returns new length (a number)
mutates the array

pair with shift()  → queue at the front
vs push()          → push adds at the end

Syntax

Call array.unshift. Start with this line.

JavaScript
array.unshift(...items)
CallWhat it does
array.unshift(...items)Primary signature.
array.unshift(...)Call with the arguments your case needs.

Built into JavaScript. Call unshift(...) on an array instance — no import required.

Library declarations
JavaScript
array.unshift(...items)

Parameters

ParameterDescription
ArrayRequired. Target to grow at the front
...itemsOptional. Values to prepend (zero or more)

Return Value

Return ValueDescription
*New length (number)

JavaScript Examples

Example 1 — Add Elements to the Beginning

Prepend 1 and 2 onto a number list.

JavaScript
const numbers = [3, 4, 5];

numbers.unshift(1, 2);

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

How It Works

  1. Start with three numbers. Length is 3; first value is 3.
  2. Pass two arguments. unshift(1, 2) inserts both at the front, in that order.
  3. Old values shift right. 3 moves from index 0 to 2.
  4. Same array object. numbers was mutated — no new array created.

Example 2 — unshift() Returns the New Length

Capture the return value — it is a number, not the array.

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

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

console.log(newLength);
// 3
console.log(items);
// ["a", "b", "c"]
Try It Yourself

How It Works

  1. Start with two items. Length is 2.
  2. Unshift one more. Length becomes 3.
  3. Return value is 3. Stored in newLength.
  4. Do not chain. items.unshift("x").map(...) fails because 3 has no map.

Example 3 — unshift() vs push()

Same value, different ends of the array.

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

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

console.log(start);
// [1, 2, 3]
console.log(end);
// [2, 3, 1]
Try It Yourself

How It Works

  1. Same starting list. Both copies begin as [2, 3].
  2. unshift(1) prepends. 1 becomes the new first element.
  3. push(1) appends. 1 becomes the last element.
  4. Pick by position. Front → unshift; end → push.
Compatibility

Browser & Runtime Support

Array.prototype.unshift() is one of the oldest array methods, available since JavaScript 1.2 / ES3.

✓ Baseline · ES3

Array.prototype.unshift()

Supported in every browser ever shipped with JavaScript arrays, including Internet Explorer, and all Node.js versions.

100% Universal support
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Bun Supported · JavaScript runtime
Supported
Deno Supported · JavaScript runtime
Supported
Node.js Supported · Server runtime
Supported
Android WebView Supported · Modern WebView
Full support
Array.unshift() Universal

Bottom line: Safe to use in any environment. No polyfill needed.

Frequently Asked Questions

unshift() adds one or more elements to the beginning of an array, shifts existing elements to higher indexes, increases length, and returns the new length.
Yes. unshift() changes the original array in place. Use spread ([...items, ...arr]) or concat when you need a new array without mutating the original.
The new length of the array after insertion—not the array itself. This matches push() behavior.
unshift() adds at index 0 (the start). push() adds at the end. unshift() is slower on large arrays because every existing element moves one index right.
unshift() adds to the front. shift() removes from the front. They are opposites at the start of the array.
unshift() has been available since JavaScript 1.2 / ES3 and works in every browser and Node.js environment.

Next: values()

Learn how to get an iterator over an array’s values.

values() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

14 people found this page helpful

JavaScript Array toString() Method JavaScript Array values() Method