Array.prototype.toSpliced()

toSpliced(start, deleteCount, ...items)

Returns: array · Added in vES2023 · Updated March 16, 2026 · Array Methods

array splice immutable

The toSpliced() method returns a new array with elements removed or replaced at a given index. Unlike splice() which mutates the original array, toSpliced() leaves your original data intact — essential for React state, Redux, and other immutability-required workflows.

Syntax

arr.toSpliced(start)
arr.toSpliced(start, deleteCount)
arr.toSpliced(start, deleteCount, ...items)

Parameters

Parameter	Type	Description
`start`	number	Index at which to start changing the array
`deleteCount`	number	Optional number of elements to remove
`...items`	any	Optional elements to add to the array

Return Value

A new array with the specified changes applied. The original array is not modified.

Examples

Removing elements

const arr = ["a", "b", "c", "d", "e"];
const removed = arr.toSpliced(1, 2);
console.log(arr);    // ["a", "b", "c", "d", "e"] (unchanged)
console.log(removed); // ["a", "d", "e"]

Replacing elements

const fruits = ["apple", "banana", "cherry", "date"];
const swapped = fruits.toSpliced(1, 2, "orange", "grape");
console.log(fruits);    // ["apple", "banana", "cherry", "date"] (unchanged)
console.log(swapped); // ["apple", "orange", "grape", "date"]

Inserting without removing

const colors = ["red", "blue"];
const inserted = colors.toSpliced(1, 0, "green", "yellow");
console.log(colors);    // ["red", "blue"] (unchanged)
console.log(inserted); // ["red", "green", "yellow", "blue"]

Working with objects

const todos = [
  { id: 1, text: "Buy milk" },
  { id: 2, text: "Walk dog" },
  { id: 3, text: "Write code" }
];

const updated = todos.toSpliced(1, 1, { id: 2, text: "Feed cat" });
console.log(todos.length);     // 3 (unchanged)
console.log(updated.length);  // 3
console.log(updated[1].text); // "Feed cat"

Negative indices

const letters = ["a", "b", "c", "d"];
const fromEnd = letters.toSpliced(-2, 1, "x");
console.log(letters);    // ["a", "b", "c", "d"] (unchanged)
console.log(fromEnd);   // ["a", "b", "x", "d"]

Practical: replacing item in React-style state

// Simulating React state update
let items = ["foo", "bar", "baz"];

// Old way with mutation (bad in React/Redux):
// items.splice(1, 1, "qux");

// New way with immutability:
items = items.toSpliced(1, 1, "qux");
console.log(items); // ["foo", "qux", "baz"]

When to Use toSpliced()

Choose toSpliced() over splice() when:

Working with React state or Redux
You need to preserve the original array for comparison
Chaining with other array methods
Functional programming patterns