splice

The splice() function removes a number of elements from a list a specified starting index. Optionally, you can add any number of new elements at that starting index as well. The function returns a new list that reflects the changes (it does not modify the original list).

In simpler words, splice() lets you delete elements from the middle of a list, and/or add new elements into the middle as well.

splice(list, startIndex, deleteCount?, ...)
list.splice(startIndex, deleteCount?, ...) 

/* "?" denotes an optional argument */
Code language: JavaScript (javascript)

This function is very similar the JavaScript’s toSpliced() method:

Array.prototype.toSpliced() – JavaScript | MDN

The toSpliced() method of Array instances is the copying version of the splice() method. It returns a new array with some elements removed and/or replaced at a given index.

developer.mozilla.org

The input list can be a list with any number of elements, and each element can have any type.

The startIndex is an integer that specifies the zero-based index on which to perform the function’s specified actions (deleting elements and/or adding new ones).

startIndex can be a negative integer, which will cause it to count from the end of the list, rather than the beginning:

[1, 2, 3, 4, 5].splice(-1, 1) /* Output: [1, 2, 3, 4] */
Code language: JavaScript (javascript)

Note how an index of -1 removes the last element of the list. There’s no -0 position!

There are two cases where a startIndex value will cause any deleteCount to be ignored (or treated as 0), making the function only add elements:

1. startIndex >= list.length()
2. startIndex < -list.length() (i.e. a negative startIndex has a higher absolute value than list.length())

When the deleteCount is greater than 0, deletions start at the startIndex, not after. For example:

[1, 2, 3, 4, 5].splice(1, 1) /* Output: [1, 3, 4, 5] */
Code language: JavaScript (javascript)

When you add new elements, they’re always added at the startIndex. In the case that your deleteCount is greater than 0, added elements will begin replacing the deleted ones:

[1, 2, 3, 4, 5].splice(1, 1, "👀") /* Output: [1, "👀", 3, 4, 5]

[1, 2, 3, 4, 5].splice(1, 1, "👀").at(1) /* Output: "👀" */
Code language: JavaScript (javascript)

However, if your deleteCount is 0 (or negative), no elements will be removed. Instead, the added elements merely push the existing elements forward. Notice how 👀 ends up before 2, which was the original value at the index of 1:

[1, 2, 3, 4, 5].splice(1, 0, "👀") /* Output: [1, "👀", 2, 3, 4, 5]

[1, 2, 3, 4, 5].splice(1, 0, "👀").at(1) /* Output: "👀" */
Code language: JavaScript (javascript)

The same will be true if deleteCount is smaller than the number of elements added.

You can add any number of new elements to the list by specifying them as arguments:

[1, 2, 3, 4, 5].splice(2, 1, "🦍", "🐕", "🦙") 
/* Output: [1, 2, 🦍, 🐕, 🦙, 4, 5] */
Code language: JavaScript (javascript)

Example Formulas

Replacing an incorrect element:

lets(
  startingList, [1, 2, 4, 4, 5],
  
  fixedList, startingList.splice(2, 1, 3),
  
  "Starting list: [ " + 
  startingList.join(", ") + 
  " ]\nEnding list: [ " + 
  fixedList.join(", ") + " ]"
)

/* Output:

Starting list: [ 1, 2, 4, 4, 5 ]
Ending list: [ 1, 2, 3, 4, 5 ]

*/
Code language: JavaScript (javascript)

Adding missing elements:

lets(
  startingList, ["articuno", "bulbasaur", "farfetch'd"],
  
  fixedList, startingList.splice(2, 0, "charmander", "dugtrio", "ekans"),
  
  "Starting list: [ " + 
  startingList.join(", ") + 
  " ]\nEnding list: [ " + 
  fixedList.join(", ") + " ]"
)

/* Output:

Starting list: [ articuno, bulbasaur, farfetch'd ]
Ending list: [ articuno, bulbasaur, charmander, dugtrio, ekans, farfetch'd ]

*/
Code language: JavaScript (javascript)

Counting from the end of the list:

lets(
  startingList, [1, 2, 3, 4, 2],
  
  fixedList, startingList.splice(-1, 1, 5),
  
  "Starting list: [ " + 
  startingList.join(", ") + 
  " ]\nEnding list: [ " + 
  fixedList.join(", ") + " ]"
)

/* Output:

Starting list: [ 1, 2, 3, 4, 2 ]
Ending list: [ 1, 2, 3, 4, 5 ]

*/
Code language: JavaScript (javascript)

Chaining splice() instances:

lets(
  startingList, [1, 2, 1, 8, 2],
  
  fixedList, startingList
    .splice(-1, 1, 9)
    .splice(2, 1, 3, 4, 5, 6, 7),
  
  "Starting list: [ " + 
  startingList.join(", ") + 
  " ]\nEnding list: [ " + 
  fixedList.join(", ") + " ]"
)

/* Output:

Starting list: [ 1, 2, 1, 8, 2 ]
Ending list: [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ]

*/
Code language: JavaScript (javascript)

View and duplicate an example Notion database with all of these examples:

Notion

A tool that connects everyday work into one space. It gives you and your teams AI tools—search, writing, note-taking—inside an all-in-one, flexible workspace.

thomasfrank.notion.site