JavaScript Array.toSpliced() method (with examples)

This succinct, code-centric article is about the Array.toSpliced() method in modern JavaScript.

Overview

The Array.toSpliced() method is a new feature that was introduced in ECMAScript 2023 (ES14). At the time of writing, most modern web browsers support it (on both desktop and mobile).

The purpose of the Array.toSpliced() method is to create a new array with some elements removed and/or replaced at a given index, without modifying the original array. It is similar to the Array.splice() method, but the key difference is that it does not mutate the source array and it does not return the deleted elements.

Syntax:

array.toSpliced(start, deleteCount, item1, item2, ..., itemN)

Parameters explained:

• start: A zero-based index at which to start changing the array. A negative index counts back from the end of the array. If omitted or less than -array.length, 0 is used. If greater than or equal to array.length, no element will be deleted, but new elements will be added at the end of the array.
• deleteCount: An integer indicating the number of elements to remove from start. If omitted or greater than or equal to the number of elements after start, all elements from start to the end of the array will be deleted. If 0 or negative, no elements are removed. In this case, at least one new element should be specified.
• item1, item2, ..., itemN: The elements to add to the array, beginning from start. If no elements are specified, toSpliced() will only remove elements from the array.

The return value is a new array that consists of all elements before start, item1, item2, …, itemN, and all elements after start + deleteCount.

The Array.toSpliced() method might be harder to understand than other array methods in JavaScript. For more clarity, see the practical examples below.

Examples

Copying a part of an array

This example demonstrates how to use the Array.toSpliced() method to copy a part of a given array without modifying it.

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

// Copy from index 1 to index 3 (exclusive)
const sliced = numbers.toSpliced(1, 2);

// Original array remains intact
console.log(numbers); 
// Output: [1, 2, 3, 4, 5]

// New array contains copied elements from index 1 to 3 (exclusive)
console.log(sliced); // [1, 4, 5]

Inserting an element at a specific index

Suppose we have an array of months and we want to insert Feb at index 1. We can use the Array.toSpliced() method with start = 1, deleteCount = 0, and item1 = “Feb” to get the job done.

const months = ["Jan", "Mar", "Apr", "May", "Jun"];

// Inserting an element at index 1
const months2 = months.toSpliced(1, 0, "Feb");

// months2 is a new array
console.log(months2); // ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]

// Original array is not modified
console.log(months); // ["Jan", "Mar", "Apr", "May", "Jun"]

Deleting two elements starting from a given position

Let’s say we have an array of words and we want to delete the two ones from index 2. We can use the Array.toSpliced() method with start = 2 and deleteCount = 2 to create a new array with two elements removed from index 2.

// an array of words
const words = ["Wolf", "Sheep", "Duck", "Dragon", "Turtle", "Sling Academy"];

// Deleting two elements starting from index 2
const result = words.toSpliced(2, 2);
console.log(result); 
// Output: ['Wolf', 'Sheep', 'Turtle', 'Sling Academy']


// Original array is not modified
console.log(words);
// Output: ['Wolf', 'Sheep', 'Duck', 'Dragon', 'Turtle', 'Sling Academy']

Replacing one element with two elements

Imagine we have an array of items and we want to replace the one at index 2 with two other items. Below is the solution that makes use of the Array.toSpliced() method:

const items = ["Item A", "Item B", "Item C", "Item D"];

// Replacing one element at index 2 with two new elements
const items2 = items.toSpliced(2, 1, "Robot", "Dinosaur");
console.log(items2); 
// Output: ["Item A", "Item B", "Robot", "Dinosaur", "Item D"]
// "Item C" is replaced with "Robot" and "Dinosaur"

// Original array is not modified
console.log(items); 
// Output: ["Item A", "Item B", "Item C", "Item D"]

Final Thoughts

The Array.toSpliced() method is a useful addition to the JavaScript language. It allows programmers like you and me to manipulate arrays without modifying the original ones, which can prevent unwanted side effects and make the code more readable and maintainable. The method also provides a convenient way to insert, delete, or replace elements at any index of an array.

It is a good practice to use the Array.toSpliced() method instead of the Array.splice() method whenever possible, unless you need to access the deleted elements or modify the source array for some reason.