JavaScript Reference ยท Array
Array.prototype.toSpliced()
Reference for JavaScript Array.prototype.toSpliced(): remove, replace or insert elements and get a new array back, while the original stays unchanged.
The toSpliced() method does what splice() does, but on a copy. You tell it where to start, how many elements to remove and which elements to insert, and it returns a new array with that change applied. The original array is left alone.
That makes it a good fit for code that treats data as immutable, such as state updates in UI code. With splice() you get back the removed elements and the array is changed in place. With toSpliced() you get back the finished result.
const list = ["a", "b", "c", "d"]; const next = list.toSpliced(1, 2, "X"); // next is ["a", "X", "d"], list is still ["a", "b", "c", "d"]
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
array.toSpliced() array.toSpliced(start) array.toSpliced(start, deleteCount) array.toSpliced(start, deleteCount, item1, item2, /* โฆ, */ itemN)
| Name | Description |
|---|---|
start |
Zero-based index where changes begin. It is converted to an integer. A negative value counts from the end. Values below -length are treated as 0, and values above length are treated as length. |
deleteCount |
Optional. How many elements to leave out, starting at start. If you omit it (but pass start), everything from start to the end is left out. A negative or NaN count is treated as 0. |
item1, โฆ, itemN |
Optional. Elements to insert at start. |
Return value: a new array with the elements removed and inserted as described.
Exceptions: TypeError if the resulting array would be longer than the maximum safe length (2^53 - 1). In practice you will not meet this.
Usage notes
- No mutation. The array you call it on is not changed. The result is a new array, so
result !== arrayeven when nothing was removed or inserted. - Shallow copy. The new array holds the same element references. If the elements are objects, both arrays point to the same objects.
- You do not get the removed elements. If you need them, use
splice(), or read them first withslice(). - Argument handling matches
splice()with one difference: callingtoSpliced()with no arguments returns an unchanged copy, andtoSpliced(start)removes everything fromstartonward. - Holes become
undefined. The method reads every index, so empty slots in a sparse array turn into realundefinedvalues in the copy. - Generic. It also works on array-like objects through
Array.prototype.toSpliced.call(obj, ...), always returning a real array. - Pairs with the other copying methods:
toSorted(),toReversed()andwith()follow the same idea of returning a changed copy. - Performance. Like any copy, it takes time proportional to the array's length. For a huge array that you change in a loop, a mutating
splice()on a private working copy can be cheaper.
Browser support
toSpliced() is part of the "change array by copy" methods and is available in current browsers, but it is recent. Check a compatibility table if you support older browsers or older Node.js versions.