Array.prototype.unshift()
Baseline
Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
The unshift() method of Array instances adds the specified elements to the
beginning of an array and returns the new length of the array.
Try it
const array = [1, 2, 3];
console.log(array.unshift(4, 5));
// Expected output: 5
console.log(array);
// Expected output: Array [4, 5, 1, 2, 3]
Syntax
unshift()
unshift(element1)
unshift(element1, element2)
unshift(element1, element2, /* …, */ elementN)
Parameters
element1, …,elementN-
The elements to add to the front of the
arr.
Return value
The new length property of the object upon which the
method was called.
Description
The unshift() method inserts the given values to the beginning of an
array-like object.
Array.prototype.push() has similar behavior to unshift(), but applied to the end of an array.
Please note that, if multiple elements are passed as parameters, they're inserted in
chunk at the beginning of the object, in the exact same order they were passed as
parameters. Hence, calling unshift() with n
arguments once, or calling it n times with
1 argument (with a loop, for example), don't yield the same results.
See example:
let arr = [4, 5, 6];
arr.unshift(1, 2, 3);
console.log(arr);
// [1, 2, 3, 4, 5, 6]
arr = [4, 5, 6]; // resetting the array
arr.unshift(1);
arr.unshift(2);
arr.unshift(3);
console.log(arr);
// [3, 2, 1, 4, 5, 6]
The unshift() method is generic. It only expects the this value to have a length property and integer-keyed properties. Although strings are also array-like, this method is not suitable to be applied on them, as strings are immutable.
Examples
Using unshift()
const arr = [1, 2];
arr.unshift(0); // result of the call is 3, which is the new array length
// arr is [0, 1, 2]
arr.unshift(-2, -1); // the new array length is 5
// arr is [-2, -1, 0, 1, 2]
arr.unshift([-4, -3]); // the new array length is 6
// arr is [[-4, -3], -2, -1, 0, 1, 2]
arr.unshift([-7, -6], [-5]); // the new array length is 8
// arr is [ [-7, -6], [-5], [-4, -3], -2, -1, 0, 1, 2 ]
Calling unshift() on non-array objects
The unshift() method reads the length property of this. It shifts all indices in the range 0 to length - 1 right by the number of arguments (incrementing their values by this number). Then, it sets each index starting at 0 with the arguments passed to unshift(). Finally, it sets the length to the previous length plus the number of prepended elements.
const arrayLike = {
length: 3,
unrelated: "foo",
2: 4,
};
Array.prototype.unshift.call(arrayLike, 1, 2);
console.log(arrayLike);
// { '0': 1, '1': 2, '4': 4, length: 5, unrelated: 'foo' }
const plainObj = {};
// There's no length property, so the length is 0
Array.prototype.unshift.call(plainObj, 1, 2);
console.log(plainObj);
// { '0': 1, '1': 2, length: 2 }
Specifications
| Specification |
|---|
| ECMAScript® 2027 Language Specification # sec-array.prototype.unshift |
Browser compatibility
| desktop | mobile | server | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
unshift
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support