How to Use JavaScript Array Splice
Tags: javascript, programming, tutorial, webdev
Published: 2023-11-17 10:14:04


<a href="https://github.com/refinedev/refine">
    <img src="https://refine.ams3.cdn.digitaloceanspaces.com/blog-banners/twitter-2.png" alt="refine repo" /> 


## Introduction

 `Array.prototype.splice()` is a JavaScript `Array` method that is used to remove, replace or insert items starting at a chosen index. It is also an effective tool for adding items to the end of an array.


`Array.prototype.splice()` is a sparsely used but powerful JavaScript method for manipulating arrays **in place**. This means, we are mutating the actual array, not a copy of it. JavaScript `splice()` is useful for wiping all items after `n` number of initial items. It is handy for removing a number of intermediary items starting at an indicated index. It is especially needed for inserting items when we want to replace items or overload an array besides replacement. JavaScript `splice()` offers an alternative to `Array.prototype.push()` for growing the tail of the array as well.

Unlike several other `Array` methods, JavaScript `slice()` does not have a `String` equivalent.

In this post, we play around to illustrate various use cases of JavaScript `splice()` with trivial examples. We start with the method signature for `Array.prototype.splice()`, its possible parameters (`startIndex`, `deleteCount`, `item`s) and what they represent. We then go ahead and see examples of using combinations of passed arguments to manipulate an array. 

In particular, we observe how to wipe out items from a certain index onward. We also go through examples of replacing existing items with new ones. We explore how to insert items in the case of overloaded replacement and injection. We also figure out `splice()` way of adding items to the tail of the array.

Towards the end, we touch base on the nuances of the values passed as `startIndex` and learn how JavaScript `splice()` behaves when `startIndex` argument is negative or greater than the array length.

## JavaScript Splice

When called by an array, JavaScript `splice()` takes three possible arguments: `startIndex`, `deleteCount` and `item`s list. Of these three types of arguments, `startIndex` indicates a zero-based index at which mutation kicks off. `deleteCount` denotes the number of items to be deleted and `item`s is a possibly infinite list of items to be inserted.

### JS `Array.prototype.splice()` Method Signature

Possible call signatures for JavaScript `splice()` are:

```js
splice()
splice(startIndex)
splice(startIndex, deleteCount, item1)
splice(startIndex, deleteCount, item1, item2, /*...*/, itemN)
```

None of the arguments for `Array.prototype.splice()` are required. However, when we want to mutate the caller array, we have to pass the `startIndex` as a minimum. Passing `deleteCount` depends on whether we want to delete any item/s or not. And passing the `item`s list depends on whether/what we want to insert or add to the array. It is also possible to pass all arguments at the same time. In the coming sections, we consider most of the cases.



### JS `splice()` Result / Return Value

As we'll start seeing next, `splice()` mutates the original array and returns an array containing **removed items**.

### JS `Array.prototype.splice()` without Arguments

Although, JavaScript `splice()` attempts to mutate the caller array, the returned value is **_an array of removed items_**. We can get a hint of the return value when an array calls it without passing any argument:

```js
const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];

// Return value
console.log(mnemonic.splice()); // []

console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "And", "Zebras", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]
```

As we can see, `splice()` without argument returns an empty array `[]`. And as we'll see it become clearer in the next section, it is an array of removed items. In the case above, since no item is being removed, it is empty.

Notice that, although `splice()` is geared to remove items, it did not mutate the caller above, since we have not passed `startIndex`.

### Wiping All After `n` Items - JavaScript `splice()` with Only `startIndex`

When we pass `startIndex`, we should expect the caller array to mutate.

With **only** `startIndex` passed to JavaScript `splice()`, all items including the one **at and after** `startIndex` are removed:

```js
const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];

// Return value
console.log(mnemonic.splice(4)); // ["And", "Zebras", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]

// Caller array
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys"]
```

We can clearly see from this example that the returned array now has items including the one at `startIndex` (`4`) till the end **removed**. In other words, they were wiped out and the items upto `startIndex` are remaining in the original array.

It is important to notice that removal begins at `startIndex` **included**. This gives rise to a noticeable pattern where the zero based `startIndex` actually corresponds to first **n** items **remaining** in the caller array, i.e. `n = startIndex`:

```js
const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];

// Wiping all after first 4 items
console.log(mnemonic.splice(4)); // ["And", "Zebras", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys"]

// Wiping all after first 2 items
console.log(mnemonic.splice(2)); // ["Cats", "Monkeys"]
console.log(mnemonic); // ["Please", "Send"]

// Wiping all items
console.log(mnemonic.splice(0)); // ["Please", "Send"]
console.log(mnemonic); // []
```

In the above examples, for each of the values passed as `startIndex`, we want that number of items to remain at the head of the original array. With `mnemonic.splice(0)`, we are emptying the original array.






### Deleting Intermediary Items with JS `Array.prototype.splice()`

We can remove intermediary items from an array by passing `deleteCount` as the second argument. This removes the indicated number of items beginning at `startIndex`:

```js
const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];
console.log(mnemonic.splice(4, 2)); // ["And", "Zebras"]
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]
```

In the above call, we are passing `2` as `deleteCount`. Deleting starts at `startIndex` and ends at the index where `deleteCount` is achieved. Notice, removal slides the items after `deleteCount` to the **left**.

### Replacing Items with JS `Array.prototype.splice()`

We can replace removed items with new ones by passing in items as a list after the second argument. All items passed are added **_to `startIndex` onwards_**:

```js
const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];
console.log(mnemonic.splice(4, 0, "Ants", "Zebus")); // []
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "Ants", "Zebus", "And", "Zebras", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]
console.log(mnemonic.splice(4, 2)); // ["Ants", "Zebus"]
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "And", "Zebras", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]

// Items removed first and then added
console.log(mnemonic.splice(4, 2, "Alpacas", "Zorillas"));
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "Alpacas", "Zorillas", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]
```

Observe above that deletion gains precedence over insertion. It becomes more apparent when `deleteCount` is positive and items are replaced or added with arguments after . In the above series of mutations,`"Ants", "Zebus"` first inserted at `4`, with `0` items removed first. Then they were removed with `4` as `startIndex`, `2` as `deleteCount` and no items replacing them. In the last mutation, further removal of `2` items at index `4` happens, that are replaced subsequently with the new items.

We can actually go further and overload the array by adding more items than removed:

```js
const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];

// Add more items than removed
console.log(mnemonic.splice(4, 2, "Ants", "Zebus", "Donkeys", "Bears")); // ["And", "Zebras"]
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "Ants", "Zebus", "Donkeys", "Bears", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]
```

Notice that because we are replacing or overloading items, the items that come after get displaced towards the **right**.

### Items Injection with `Array.prototype.splice()`

You might already noticed that, if we want to only inject items at a certain point in the array, we can pass `0` as `deleteCount`:

```js
const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];
console.log(mnemonic.splice(4, 0, "Ants", "Zebus", "Donkeys", "Bears")); // []
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "Ants", "Zebus", "Donkeys", "Bears", "And", "Zebras", "In", "Large", "Cages", "Make", "Sure", "Padlocked"]
```

New items are added starting at `startIndex` directly because with `deleteCount` set to `0`, so no items are deleted.

### Tailgrowing with `Array.prototype.splice()`

We can add to the tail by using the `length` of the caller array as `startIndex`:

```js
const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];
console.log(
  mnemonic.splice(mnemonic.length, 0, "Ants", "Zebus", "Donkeys", "Bears")
); // []
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "In", "Large", "Cages", "Make", "Sure", "Padlocked", "Ants", "Zebus", "Donkeys", "Bears"]
```

Caller `length` finds the tail for an incoming item as `length` is greater than the last index in the zero-index based array. Using `length` like this with `splice()` is a good occasional alternative to `Array.prototype.push()`.

It important to caution that using `-1` as `startIndex` **doesn't** add to the tail. That's because for `startIndex < 0`, mutation starts at `startIndex + mnemonic.length`. So, the last item always gets displaced as last and we never add to the tail:

```js
const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];
console.log(mnemonic.splice(-1, 0, "Ants", "Zebus", "Donkeys", "Bears")); // []
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "And", "Zebras", "In", "Large", "Cages", "Make", "Sure" "Ants", "Zebus", "Donkeys", "Bears", "Padlocked"]
```

A variation of this next.

### Inject Items Before Last `n` Items - JavaScript `slice()` with Negative `startIndex`

We can inject new items before last `n` items by passing in `-n` as `startIndex`. This is another example when `startIndex < 0`:

```js
const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];

// Inject before last 2 items
console.log(mnemonic.splice(-2, 0, "Ants", "Zebus", "Donkeys", "Bears")); // []
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "And", "Zebras", "In", "Large", "Cages", "Make", "Ants", "Zebus", "Donkeys", "Bears", "Sure", "Padlocked"]

// Inject before last 4 items
console.log(mnemonic.splice(-4, 0, "Apacas", "Zorillas")); // []
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "And", "Zebras", "In", "Large", "Cages", "Make", "Ants", "Zebus", "Apacas", "Zorillas", "Donkeys", "Bears", "Sure", "Padlocked"]
```

Again, a negative `startIndex` brings `-n + mnemonic.length` to play. So, mutation starts at `n` items (**not** indexes) from the end of the array -- keeping last `n` items intact in the tail.

## Nuances of JS `Array.prototype.splice()`

In this section, let's consider other quirks of using JavaScript `slice()`.

### Higher Negatives of `startIndex`

There is another nuance of using negative `startIndex` with `splice()`. For example, when `startIndex < -mnemonic.length`, it is effectively `0`:

```js
const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];
console.log(mnemonic.splice(-100, 10, "Ants", "Zebus", "Donkeys", "Bears")); // ["Please", "Send", "Cats", "Monkeys", "And", "Zebras", "In", "Large", "Cages", "Make"]
console.log(mnemonic); // ["Ants", "Zebus", "Donkeys", "Bears", "Sure", "Padlocked"]
```

Here, with `startIndex` value of `-100`, removal starts at index `0` and first `10` items are removed. The passed items are added after removal at index `0`.

<br />

### Higher `startIndex` Value

When `startIndex` is greater than the length of the array, no items is deleted even if `deleteCount` is passed. Plus all passed items are tucked to the tail:

```js
const mnemonic = [
  "Please",
  "Send",
  "Cats",
  "Monkeys",
  "And",
  "Zebras",
  "In",
  "Large",
  "Cages",
  "Make",
  "Sure",
  "Padlocked",
];
console.log(mnemonic.splice(100, 10, "Ants", "Zebus", "Donkeys", "Bears")); // []
console.log(mnemonic); // ["Please", "Send", "Cats", "Monkeys", "And", "Zebras", "In", "Large", "Cages", "Make", "Sure", "Padlocked", "Ants", "Zebus", "Donkeys", "Bears"]
```

As we can see, `100` is far greater than `mnemonic.length`, and we asked for deletion of `10` items somewhere non-existent. So, none is deleted inside the array. And passed items are added to the tail.

Using an arbitrary higher index is, however, not safe for tailgrowing, since it does not always make sure `startIndex` is greater or equal to caller `length`.

## Summary

In this post, explored various cases and patterns of using JavaScript `splice()`. We learned that `Array.prototype.splice()` is an array method and it doesn't have a `String` equivalent. We also understood that it mutates the original array and returns an array of removed items.

We found out how to wipe out all items after first `n` items by passing `n` as the `startIndex` to `splice()`. We illustrated how to remove intermediary items by passing `deleteCount` as the second argument. We also saw how to replace removed items by passing in new items as third argument and onward. We learned how to inject items with `0` passed as `deleteCount`.

We figured out an alternative to `Array.prototype.push()` by using `Array.prototype.splice()` with caller `length` passed as `startIndex`. We also discovered the pattern of adding items prior to last `n` items using `-n` as the `startIndex`. In the end, we explored the quirks of using extreme values of `startIndex`, particularly when it is more negative than `-length` of the caller array and when it is higher than `length`.


**Author: <a  target="_blank" href="https://refine.dev/blog/author/abdullah_numan/">Abdullah Numan</a>**