The JavaScript array.toSpliced() method
The toSpliced() method returns a new array with elements removed and/or inserted, leaving the original unchanged: the non-mutating version of splice(). arr.toSpliced(1, 2) returns a copy with two elements removed at index 1. Unlike splice(), it returns the new array (not the removed items).
Overview
toSpliced() is the non-mutating counterpart to splice(). It takes the same arguments (a start index, how many to delete, and any items to insert), but instead of changing the array in place and returning the removed elements, it returns a new array with the change applied and leaves the original alone.
This solves the classic splice() footgun: accidentally mutating an array other code still relies on. const updated = items.toSpliced(2, 1) gives you a copy with the item at index 2 removed, perfect for immutable state (React and friends) where you build a new array rather than mutating.
It belongs to the family of recent non-mutating array methods (alongside toSorted(), toReversed() and with()) that return copies. The key behavioral difference from splice() is the return value: splice() returns the removed elements, but toSpliced() returns the resulting array. Support is solid in current browsers; the spread-and-slice idiom is the fallback for older ones.
Syntax
const updated = array.toSpliced(start, deleteCount, ...items)
[1, 2, 3, 4].toSpliced(1, 2) // [1, 4] (original unchanged)
[1, 2, 3].toSpliced(1, 0, "x") // [1, "x", 2, 3] (insert)Parameters
The array.toSpliced() method accepts the following parameters.
| Parameter | Description |
|---|---|
start |
Index at which to begin changing the array. Negative counts from the end. |
deleteCount |
Optional. How many elements to remove from start. |
items |
Optional. Elements to insert at start. |
Example
<pre id="out" style="font:15px ui-monospace,monospace"></pre>
<script>
const items = ['a', 'b', 'c', 'd'];
const result = items.toSpliced(1, 2); // remove 2 at index 1
document.getElementById('out').textContent =
'result: ' + result.join(', ') + '\n' +
'original: ' + items.join(', '); // result: a, d / original: a, b, c, d
</script>Best practices
- Use
toSpliced()when you need a copy with edits and must keep the original, ideal for immutable state. - Remember it returns the new array, whereas splice() returns the removed elements.
- Pair it with toSorted(), toReversed() and with() for fully non-mutating edits.
- Use the mutating splice() only when changing the array in place is intended.
Frequently asked questions
What is the difference between toSpliced() and splice()?
toSpliced() returns a new array and leaves the original unchanged; splice() mutates the array and returns the removed elements.How do I remove an item without mutating the array?
arr.toSpliced(index, 1), which returns a copy with that element removed.How do I insert without mutating?
0 as the delete count: arr.toSpliced(index, 0, item).