The toSpliced() method

JavaScriptJunior~3 min read

toSpliced() is the new non-mutating counterpart of the splice() method, added to the standard in ECMAScript 2023 (ES14). It removes, adds or replaces elements, but instead of changing the original array it returns a new copy with those changes applied.

Theory

TL;DR

toSpliced() does the same job as splice(): it removes, inserts and replaces elements.
The original array stays unchanged, the method returns a new array.
The syntax is identical: array.toSpliced(start, deleteCount, ...items).
It returns the whole new array, not the removed elements the way splice() does.
Added in ECMAScript 2023, together with toSorted(), toReversed() and with().
Used wherever immutability matters: React, Redux, pure functions.

Quick example

javascript

const arr = [1, 2, 3, 4, 5];

// remove 2 elements starting at index 1
const newArr = arr.toSpliced(1, 2);

console.log(newArr); // [1, 4, 5]
console.log(arr);    // [1, 2, 3, 4, 5], the original is untouched

Syntax and parameters

javascript

const newArray = array.toSpliced(start, deleteCount, ...items);

Parameter	Description
`start`	The index at which the changes begin
`deleteCount`	How many elements to remove
`...items`	The elements to insert in that place (optional)

A negative start counts from the end of the array, exactly as in splice(). If deleteCount is omitted, every element from start to the end is removed.

Removing elements

javascript

const arr = [1, 2, 3, 4, 5];
const newArr = arr.toSpliced(1, 2); // remove 2 elements starting at index 1

console.log(newArr); // [1, 4, 5]
console.log(arr);    // [1, 2, 3, 4, 5], the original is untouched

What happened:

[2, 3] was removed;
the new array [1, 4, 5] came back;
the source array stayed intact.

Adding and replacing elements

Adding, when deleteCount is zero:

javascript

const arr = [1, 2, 3];
const newArr = arr.toSpliced(1, 0, 'a', 'b');

console.log(newArr); // [1, 'a', 'b', 2, 3]
console.log(arr);    // [1, 2, 3]

Starting at index 1 we remove nothing (deleteCount = 0), insert 'a' and 'b', and get a new array back while the original does not mutate.

Replacing, when we remove and insert at the same time:

javascript

const arr = [1, 2, 3, 4];
const newArr = arr.toSpliced(1, 2, 'x', 'y');

console.log(newArr); // [1, 'x', 'y', 4]
console.log(arr);    // [1, 2, 3, 4]

Here [2, 3] was removed and 'x', 'y' were inserted in their place.

Comparison with splice()

javascript

const arr = [1, 2, 3, 4];

const mutated = arr.splice(1, 2, 'x', 'y');
console.log(arr);      // [1, 'x', 'y', 4], the source array was changed
console.log(mutated);  // [2, 3], it returns the removed elements

const newArr = [1, 2, 3, 4].toSpliced(1, 2, 'x', 'y');
console.log(newArr);   // [1, 'x', 'y', 4], a new array

The main difference is not only the mutation, but also what the method returns:

	`splice()`	`toSpliced()`
Changes the source array	Yes	No
Returns	The removed elements	The whole new array
Chainable	No	Yes
Introduced in	ES3	ES2023

Because toSpliced() returns an array, you can put it in a chain:

javascript

const result = [5, 1, 4, 2]
  .toSpliced(0, 1)   // [1, 4, 2]
  .toSorted();       // [1, 2, 4]

New method	Old counterpart	What it does	Mutates the array
`toReversed()`	`reverse()`	Reverses the order	No
`toSorted()`	`sort()`	Sorts	No
`toSpliced()`	`splice()`	Removes, inserts, replaces	No
`with()`	`arr[index] = value`	Changes an element by index	No

All four return a shallow copy: nested objects in the new array are still the very same references as in the old one.

When to use it

When you need to change an array without side effects: in React, Redux or any immutable code.
When the original data must be preserved for comparison or for undo.
When state is compared by reference: a new array guarantees the component re-renders.

The method in brief:

Question	Answer
What it does	Builds a new version of the array with elements removed, added or replaced
Changes the source array	No
Returns	A new array
Supports insertion and replacement	Yes
Added in	ECMAScript 2023
Example	`[1, 2, 3].toSpliced(1, 1, 'X')` -> `[1, 'X', 3]`

Common mistakes

Expecting the method to return the removed elements. splice() returns what was removed, toSpliced() returns the new array. Code like const removed = arr.toSpliced(1, 2) will not give you what you expect.
Calling toSpliced() and throwing the result away. arr.toSpliced(1, 2); does nothing useful: the original is not changed and the new array is discarded immediately.
Assuming the copy is deep. It is a shallow copy, so mutating a nested object still affects both arrays.
Forgetting about environment support. The method exists in modern browsers and in Node.js from version 20; for older targets you need a polyfill or a build with the right target.
Confusing toSpliced() with slice(). slice(start, end) only cuts out a range and inserts nothing, while toSpliced() takes a deleteCount and a list of new elements.

Short Answer

Interview ready

Premium

A concise answer to help you respond confidently on this topic during an interview.