Suggest an edit

Improve this article

Refine the answer for “The toSpliced() method”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

**`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]
```

### Related non-mutating ES2023 methods

| 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.

Markdown · drag & drop images · ⌘B / ⌘I shortcuts931 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.