.toSpliced()

The toSpliced() method returns a new array, removing a specified number of elements and/or adding new elements, starting from a specified index in the original array.

Let's create an array, removing 2 elements from the original array, starting from the element with index 3:

        
          
          const months = [  'May', 'June', 'July', 'August', 'September', 'October']const newMonths = months.toSpliced(3, 2)console.log(newMonths)// ['May', 'June', 'July', 'October']
          const months = [
  'May', 'June', 'July', 'August', 'September', 'October'
]
const newMonths = months.toSpliced(3, 2)

console.log(newMonths)
// ['May', 'June', 'July', 'October']

        
        
          
            
            Copy
            Copied
            Failed to copy
          
        
      

Let's create an array, replacing the last 2 elements in the original array:

        
          
          const versions = [  'ES2016', 'ES2017', 'ES2018', 'unknown', 'unknown']const newVersions = versions.toSpliced(-2, 2, 'ES2019', 'ES2020')console.log(newVersions)// ['ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020']
          const versions = [
  'ES2016', 'ES2017', 'ES2018', 'unknown', 'unknown'
]
const newVersions = versions.toSpliced(-2, 2, 'ES2019', 'ES2020')

console.log(newVersions)
// ['ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020']

        
        
          
            
            Copy
            Copied
            Failed to copy
          
        
      

Array.toSpliced takes arguments:

• index, the position where changes start in the original array;
• number of elements to remove from the original array;
• additional arguments — elements to be added to the array.

If the index is negative, the count starts from the end of the array.

If the index does not correspond to the size of the array, the starting position for changes is determined by the sign of the index:

• negative index — elements are removed and/or added starting from the 0-th element of the original array;
• positive index — elements are added after the last element of the original array;

If the number of removed elements is less than or equal to 0, no elements are removed.

Array.toSpliced returns a new array.

The toSpliced() method can be used to get a copy of the original array after editing a sequence of elements: removing, adding, or replacing. The original array remains unchanged.

Let's create an array, adding 3 elements to the original array, starting from the element with index 1:

        
          
          const days = ['Mon', 'Fri']const workDays = days.toSpliced(1, 0, 'Tue', 'Wed', 'Thu')console.log(workDays)// ['Mon', 'Tue', 'Wed', 'Thu', 'Fri']// The original array remains unchangedconsole.log(days)// ['Mon', 'Fri']
          const days = ['Mon', 'Fri']
const workDays = days.toSpliced(1, 0, 'Tue', 'Wed', 'Thu')
console.log(workDays)
// ['Mon', 'Tue', 'Wed', 'Thu', 'Fri']

// The original array remains unchanged
console.log(days)
// ['Mon', 'Fri']

        
        
          
            
            Copy
            Copied
            Failed to copy
          
        
      

Unlike the splice() method, toSpliced() does not change the original array and does not return removed elements:

        
          
          const numbers = [10, 20, 30, 40]const newNumbers = numbers.toSpliced(1, 2)console.log(newNumbers, numbers)// [10, 40] [10, 20, 30, 40]// Here is how splice() worksconst deletedNumbers = numbers.splice(1, 2)console.log(deletedNumbers, numbers)// [20, 30] [10, 40]
          const numbers = [10, 20, 30, 40]
const newNumbers = numbers.toSpliced(1, 2)
console.log(newNumbers, numbers)
// [10, 40] [10, 20, 30, 40]

// Here is how splice() works
const deletedNumbers = numbers.splice(1, 2)
console.log(deletedNumbers, numbers)
// [20, 30] [10, 40]

        
        
          
            
            Copy
            Copied
            Failed to copy
          
        
      

💡 If the array has unfilled elements, then when executing toSpliced(), the returned array will contain undefined for such elements.

Let's replace the last element in the array:

        
          
          const colors = ['crimson', , , 'purple']console.log(colors.toSpliced(-1, 1, 'blueviolet' ))console.log(colors)// ['crimson', undefined, undefined, 'blueviolet']// ['crimson', <2 empty items>, 'purple']
          const colors = ['crimson', , , 'purple']
console.log(colors.toSpliced(-1, 1, 'blueviolet' ))
console.log(colors)
// ['crimson', undefined, undefined, 'blueviolet']
// ['crimson', <2 empty items>, 'purple']

        
        
          
            
            Copy
            Copied
            Failed to copy
          
        
      

💡 If the elements of the original array are objects, then the array returned by the toSpliced() method will contain references, not new objects. Thus, changes to an object in the original array will be visible in the created array and vice versa:

        
          
          const skills = [  {name: 'HTML'}, {name: 'CSS'}, {name: 'PHP'}]// Let's add a new elementconst result = skills.toSpliced(2, 0, {name: 'JS'})console.log(result)// [//  {name: 'HTML'}, {name: 'CSS'}, {name: 'JS'}, {name: 'PHP'}// ]// Let's change an element in the original arrayskills[0].year = 2005console.log(skills)// [{name: 'HTML', year: 2005}, {name: 'CSS'}, {name: 'PHP'}]// Changes are also visible in the created arrayconsole.log(result)// [//  { name: 'HTML', year: 2005 }, { name: 'CSS' },//  { name: 'JS' }, { name: 'PHP' }// ]
          const skills = [
  {name: 'HTML'}, {name: 'CSS'}, {name: 'PHP'}
]

// Let's add a new element
const result = skills.toSpliced(2, 0, {name: 'JS'})
console.log(result)
// [
//  {name: 'HTML'}, {name: 'CSS'}, {name: 'JS'}, {name: 'PHP'}
// ]

// Let's change an element in the original array
skills[0].year = 2005
console.log(skills)
// [{name: 'HTML', year: 2005}, {name: 'CSS'}, {name: 'PHP'}]

// Changes are also visible in the created array
console.log(result)
// [
//  { name: 'HTML', year: 2005 }, { name: 'CSS' },
//  { name: 'JS' }, { name: 'PHP' }
// ]

        
        
          
            
            Copy
            Copied
            Failed to copy
          
        
      

💡 Support for the toSpliced() method in major browsers and Node.js has appeared relatively recently. For example, trying to use toSpliced() in Node.js v.18.19.0 will result in an error:

        
          
          try {  console.log([1, 2, 3].toSpliced(1, 0, 1.5))} catch (err) {  console.error('Caught an error! Here it is: ', err.message)}// Caught an error!// Here it is: [1,2,3].toSpliced is not a function
          try {
  console.log([1, 2, 3].toSpliced(1, 0, 1.5))
} catch (err) {
  console.error('Caught an error! Here it is: ', err.message)
}
// Caught an error!
// Here it is: [1,2,3].toSpliced is not a function

        
        
          
            
            Copy
            Copied
            Failed to copy