Array.prototype.splice()
Removes, replaces, or inserts elements in place and returns an array of the removed elements.
splice(start)
splice(start, deleteCount)
splice(start, deleteCount, item1)
splice(start, deleteCount, item1, item2)
splice(start, deleteCount, item1, item2, /* …, */ itemN)- Added in JavaScript ES3
Parameters
| Parameter | Type | Description |
|---|---|---|
$start | number | Zero-based index at which to start changing the array, converted to an integer. A negative index counts back from the end. If start < -array.length, 0 is used. If start >= array.length, nothing is deleted and the method only adds elements. If start is omitted entirely, nothing is deleted. |
$deleteCountoptional | number= array.length - start | Number of elements to remove starting at start. If omitted, or greater than the number of elements after start, all elements from start to the end are deleted. If 0 or negative, no elements are removed. |
$item1, …, itemNoptional | any | The elements to add to the array, beginning from start. If none are specified, splice() only removes elements. |
Return value
ArrayAn array containing the deleted elements. If only one element is removed, an array of one element is returned. If no elements are removed, an empty array is returned.
Errors
Throws a TypeError if the resulting length would exceed 2^53 - 1, or if a target property is non-writable.
Changelog
- PHP ES3Introduced on Array.prototype.
- PHP ES2023toSpliced() added as the non-mutating counterpart.
splice() is the general-purpose in-place editor for arrays. One call can delete a run of elements, insert new ones at a position, or do both at once as a replacement. It mutates the array it is called on and hands back an array of whatever it removed.
When to reach for it
Use it when you genuinely need to modify an existing array that other code already holds a reference to — an ordered list a UI is rendering, a queue several functions share. Deleting by index is the most common case: list.splice(i, 1) removes one item and closes the gap, unlike delete list[i], which leaves a hole and does not change length.
What trips people up
The return value is the removed elements, not the modified array, so const next = arr.splice(0, 2) almost never means what the author intended.
deleteCount has an asymmetric rule: omitting it deletes everything from start onward, but passing an explicit undefined converts to 0 and deletes nothing. If you want to delete to the end and insert, pass Infinity. Because it shifts every later element, splicing inside a loop is quadratic on large arrays.
Example
When to use it
- Remove one item from a list by its index without leaving a hole
- Insert a new row at a specific position in an ordered list
- Replace a range of elements with a different number of elements
- Extract and return the tail of an array in a single call
Frequently asked questions
Does splice() modify the original array?
Yes, splice() mutates the array in place and returns only the removed elements; use toSpliced() or slice() plus concat() when you need the original left untouched.
How do I remove one element from an array by index?
Call arr.splice(index, 1), which removes exactly that element, shifts the rest down, and decrements length, unlike delete arr[index] which leaves a hole.
Why did splice() return an empty array?
Because nothing was removed: deleteCount was 0, negative, or an explicit undefined, or start was past the end of the array, so the call only inserted elements.
More examples
Removing an item by index versus delete
splice() closes the gap and shortens the array, which is what removal should mean. The delete operator only clears the slot, leaving a sparse array whose length still counts the missing element.
const withSplice = ["a", "b", "c"];
withSplice.splice(1, 1);
console.log(withSplice, withSplice.length); // ['a','c'] 2
const withDelete = ["a", "b", "c"];
delete withDelete[1];
console.log(withDelete.length); // 3 — length unchanged
console.log(1 in withDelete); // false — a hole is left behindInserting without removing
With deleteCount set to 0, splice() becomes a pure insertion at the given position and returns an empty array. A negative start of -1 inserts before the last element.
const steps = ["start", "finish"];
steps.splice(1, 0, "validate", "build");
console.log(steps); // ['start','validate','build','finish']
// Negative start counts back from the end.
steps.splice(-1, 0, "deploy");
console.log(steps); // ['start','validate','build','deploy','finish']Deleting to the end while inserting
An explicit undefined for deleteCount is coerced to 0, so nothing is removed and 9 is merely inserted. Passing Infinity is the documented way to delete everything from start onward while still adding items.
const a = [1, 2, 3, 4, 5];
a.splice(2, undefined, 9); // undefined becomes 0
console.log(a); // [1,2,9,3,4,5]
const b = [1, 2, 3, 4, 5];
b.splice(2, Infinity, 9); // Infinity deletes the rest
console.log(b); // [1,2,9]
Discussion