Skip to content
Tutorials Center
My learning

Topics

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.

JavaScript
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

JS Remove, replace and insert

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Compared with splice()

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
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 !== array even 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 with slice().
  • Argument handling matches splice() with one difference: calling toSpliced() with no arguments returns an unchanged copy, and toSpliced(start) removes everything from start onward.
  • Holes become undefined. The method reads every index, so empty slots in a sparse array turn into real undefined values 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() and with() 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.