Skip to main content

splice() in JavaScript – How to Add or Remove Array Items

Whenever you use splice() on an array, the method does the following:

  1. It alters its calling array by adding or removing a specific number of items to/from it.
  2. It returns an array containing the items removed (or an empty array if no item got removed from the calling array).
note

A calling array is an array on which you used splice(). So, in bestColorsList.splice(), bestColorsList is the calling array.

Here's an example:

// Define an array:
const colorsArray = ["red", "blue", "green", "white", "yellow", "pink"];

// Remove all colorsArray's items from the second index position:
const removedColors = colorsArray.splice(2);

console.log(removedColors);

// The invocation above will return:
["green", "white", "yellow", "pink"]

console.log(colorsArray);

// The invocation above will return:
["red", "blue"]

Try it on StackBlitz

In the snippet above, we used splice() to remove all the colorsArray's items from index 2.

In other words, we spliced (edited) colorsArray from the 2nd index position.

Let's now discuss splice()'s syntax.

Syntax of the splice() Method

callingArray.splice(startIndex, howManyItems, addItem1, ..., addItemX)

As shown in the snippet above, splice() accepts one or more arguments.

Argument 1: startIndex

The startIndex argument is the first argument accepted by the splice() method. It defines the index position where you want the splice (edit) to begin.

Keep in mind that the startIndex is part of the items that the computer will splice.

Here's an example:

const colorsArray = ["red", "blue"];
const removedColors = colorsArray.splice(0);

console.log(removedColors);

// The invocation above will return:
["red", "blue"]

console.log(colorsArray);

// The invocation above will return:
[]

Try it on StackBlitz

You can see that "red" is part of the items removed from colorsArray.

The reason "red" got removed is that the computer starts splicing (editing) an array from the startIndex (0 in this case).

Suppose the startIndex argument is greater than the calling array's length. In that case, the computer will automatically change the startIndex to the calling array's length. As such, no item will get removed.

Here's an example:

const colorsArray = ["red", "blue"];
const removedColors = colorsArray.splice(14);

console.log(removedColors);

// The invocation above will return:
[]

console.log(colorsArray);

// The invocation above will return:
["red", "blue"]

Try it on StackBlitz

You can see that splice()'s invocation returned an empty array because no item got removed from colorsArray.

In other words, the system automatically changed colorsArray.splice(14) to colorsArray.splice(2). And since no item is at the index position 2, the computer returned an empty array.

Suppose you wish to start removing items from the end of the calling array. In such a case, use a negative number as your startIndex.

Here's an example:

const colorsArray = ["red", "blue", "green", "white", "yellow", "pink"];
const removedColors = colorsArray.splice(-2);

console.log(removedColors);

// The invocation above will return:
["yellow", "pink"]

console.log(colorsArray);

// The invocation above will return:
["red", "blue", "green", "white"]

Try it on StackBlitz

You can see that the index counting started from colorsArray's last item because we used a negative number as the startIndex.

So, now that we know about the startIndex parameter, we can discuss the howManyItems argument.

Argument 2: howManyItems

The howManyItems argument is optional. It specifies the number of items you want to remove from the calling array—beginning from the startIndex.

Here's an example:

// Define an array:
const colorsArray = ["red", "blue", "green", "white", "yellow", "pink"];

// Remove four of colorsArray's items from the first index position:
const removedColors = colorsArray.splice(1, 4);

console.log(removedColors);

// The invocation above will return:
["blue", "green", "white", "yellow"]

console.log(colorsArray);

// The invocation above will return:
["red", "pink"]

Try it on StackBlitz

In the snippet above, the colorsArray.splice(1, 4) code instructs the computer to remove four of colorsArray's items—beginning from the first index position.

Suppose you omit the howManyItems argument or if it is equal to or greater than callingArray.length - startIndex (that is, the remaining items from the startIndex). In such a case, the computer will remove all the array's items—beginning from the startIndex.

Here's an example:

// Define an array:
const colorsArray = ["red", "blue", "green", "white", "yellow", "pink"];

// Remove all colorsArray's items from the first index position:
const removedColors = colorsArray.splice(1);

console.log(removedColors);

// The invocation above will return:
["blue", "green", "white", "yellow", "pink"]

console.log(colorsArray);

// The invocation above will return:
["red"]

Try it on StackBlitz

The splice() code in the snippet above removed all of the colorsArray's items—from the first index position—because we omitted the howManyItems argument.

Here's another example:

// Define an array:
const colorsArray = ["red", "blue", "green", "white", "yellow", "pink"];

// Remove all colorsArray's items from the first index position:
const removedColors = colorsArray.splice(1, 35);

console.log(removedColors);

// The invocation above will return:
["blue", "green", "white", "yellow", "pink"]

console.log(colorsArray);

// The invocation above will return:
["red"]

Try it on StackBlitz

The splice() code in the snippet above removed all of the colorsArray's items—from the first index position—because the howManyItems argument is greater than callingArray.length - startIndex (that is, 6 - 1).

In other words, the howManyItems argument is greater than the number of remaining items from the startIndex.

Keep in mind that if the howManyItems argument is zero or a negative number, the system will not remove any item from the calling array.

Here's an example:

const colorsArray = ["red", "blue", "green", "white"];
const removedColors = colorsArray.splice(1, -2);

console.log(removedColors);

// The invocation above will return:
[]

console.log(colorsArray);

// The invocation above will return:
["red", "blue", "green", "white"]

Try it on StackBlitz

You can see that none of colorsArray's items got removed because the howManyItems argument is negative.

So, now that we know about the howManyItems parameter, we can discuss the addItem1, ..., addItemX arguments.

Argument 3+: addItem1, ..., addItemX

The addItem1, ..., addItemX arguments are optional. They represent the items you want to add to the calling array beginning from the startIndex position.

Here's an example:

const colorsArray = ["red", "blue", "green", "white"];
const removedColors = colorsArray.splice(1, 2, "purple", "pink", "tan");

console.log(removedColors);

// The invocation above will return:
["blue", "green"]

console.log(colorsArray);

// The invocation above will return:
["red", "purple", "pink", "tan", "white"]

Try it on StackBlitz

The snippet above added "purple", "pink", and "tan" to colorsArray beginning from the first index position.

note
  • If you do not provide any addItem arguments, the computer will not add any new item to the calling array.
  • Suppose you wish to copy part of an array without modifying it. In that case, use slice().
  • To remove an array's first item, use shift().
  • To remove an array's last item, use pop().

Overview

This article discussed what JavaScript's splice() method does. We also used examples to see how it works.

Thanks for reading!