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 removed = items.toSpliced(1, 2); // remove 2 at index 1
document.getElementById('out').textContent =
'result: ' + removed.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, returning the result; 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).