Array.prototype.push()
Adds one or more elements to the end of an array and returns the array's new length.
push()
push(element1)
push(element1, element2)
push(element1, element2, /* …, */ elementN)- Added in JavaScript ES3
Parameters
| Parameter | Type | Description |
|---|---|---|
$element1, …, elementNoptional | any | The element(s) to add to the end of the array. |
Return value
numberThe new length property of the object upon which the method was called.
Errors
Throws a TypeError if the resulting length would exceed 2^53 - 1, or when called on a frozen array or a non-writable length property in strict mode.
Changelog
- PHP ES3Introduced on Array.prototype.
- PHP ES2015Length handling was specified up to 2^53 - 1 rather than the 2^32 - 1 limit that applies to real array indices.
push() appends elements to the end of an array, mutating it in place, and returns the new length. Together with pop() it makes an array behave as a stack. Because it writes at the end, it does not have to shift anything and is the cheapest way to grow an array.
When to reach for it
Use it to accumulate results in a loop, to collect matches while scanning, to build a stack, or anywhere you are constructing an array you own locally. When the array belongs to someone else — shared state, a function's argument — prefer concat() or spread so you do not mutate a caller's data.
What trips people up
The return value is a number, not the array, so const list = arr.push(x) stores a length and method chaining like arr.push(1).push(2) throws.
arr.push(...other) is elegant but passes every element as a separate function argument; on arrays of a hundred thousand elements or more it can exceed the engine's argument limit, so use concat() or a loop for large merges. Also note that pushing an array pushes it as a single nested element.
Example
When to use it
- Collect matching records while iterating over a data set
- Implement a stack for undo history alongside pop()
- Append parsed lines to an output buffer as a file is read
- Add an element to an array you built locally inside a function
Frequently asked questions
What does push() return?
It returns the new length of the array as a number, not the array itself, which is why push() calls cannot be chained.
How do I append one array to another?
Use arr.push(...other) for small arrays, or arr = arr.concat(other) for very large ones, since spreading passes each element as a separate argument and can exceed the engine's limit.
Is push() faster than concat()?
Yes for building up one array, because push() mutates in place while concat() allocates and copies a new array on every call, which makes concat in a loop quadratic.
More examples
Accumulating results in a loop
Each matching record is appended in order, so the result keeps the source ordering. This is the loop form of a filter and map, useful when the condition and the transform are entangled.
const records = [
{ name: "ada", active: true },
{ name: "grace", active: false },
{ name: "alan", active: true },
];
const active = [];
for (const r of records) {
if (r.active) active.push(r.name);
}
console.log(active); // ['ada','alan']
console.log(active.length); // 2A stack with push and pop
push() reports the depth of the stack after each addition, and pop() removes the most recent entry. The pair gives last-in-first-out behaviour without any extra data structure.
const history = [];
history.push("open");
history.push("edit");
const depth = history.push("save");
console.log(depth); // 3
console.log(history.pop()); // 'save' — last in, first out
console.log(history); // ['open','edit']Pushing an array versus spreading it
Passing an array directly adds it as a single element, growing the length by one. Spreading passes its elements individually, which is what you want when merging two lists.
const nested = [1, 2];
nested.push([3, 4]);
console.log(nested); // [1,2,[3,4]] — one nested element
console.log(nested.length); // 3
const flat = [1, 2];
flat.push(...[3, 4]);
console.log(flat); // [1,2,3,4]
console.log(flat.length); // 4
Discussion