Array.prototype.splice()

start

Zero-based index at which to start changing the array, converted to an integer.

• Negative index counts back from the end of the array — if -array.length <= start < 0, start + array.length is used.
• If start < -array.length, 0 is used.
• If start >= array.length, no element will be deleted, but the method will behave as an adding function, adding as many elements as provided.
• If start is omitted (and splice() is called with no arguments), nothing is deleted. This is different from passing undefined, which is converted to 0.

deleteCount Optional

An integer indicating the number of elements in the array to remove from start.

If deleteCount is omitted, or if its value is greater than or equal to the number of elements after the position specified by start, then all the elements from start to the end of the array will be deleted. However, if you wish to pass any itemN parameter, you should pass Infinity as deleteCount to delete all elements after start, because an explicit undefined gets converted to 0.

If deleteCount is 0 or negative, no elements are removed. In this case, you should specify at least one new element (see below).

item1, …, itemN Optional

The elements to add to the array, beginning from start.

If you do not specify any elements, splice() will only remove elements from the array.

An array containing the deleted elements.

If only one element is removed, an array of one element is returned.

If no elements are removed, an empty array is returned.

The splice() method is a mutating method. It may change the content of this. If the specified number of elements to insert differs from the number of elements being removed, the array's length will be changed as well. At the same time, it uses [Symbol.species] to create a new array instance to be returned.

If the deleted portion is sparse, the array returned by splice() is sparse as well, with those corresponding indices being empty slots.

The splice() method is generic. It only expects the this value to have a length property and integer-keyed properties. Although strings are also array-like, this method is not suitable to be applied on them, as strings are immutable.

splice(0, 0, ...elements) inserts elements at the start of the array like unshift().

const myFish = ["clown", "mandarin", "sturgeon"];
const removed = myFish.splice(0, 0, "angel");

// myFish is ["angel", "clown", "mandarin", "sturgeon"]
// no items removed

splice(array.length, 0, ...elements) inserts elements at the end of the array like push().

const myFish = ["angel", "clown", "mandarin"];
const removed = myFish.splice(myFish.length, 0, "sturgeon");

// myFish is ["angel", "clown", "mandarin", "sturgeon"]
// no items removed

The splice() method preserves the array's sparseness.

const arr = [1, , 3, 4, , 6];
console.log(arr.splice(1, 2)); // [empty, 3]
console.log(arr); // [1, 4, empty, 6]

The splice() method reads the length property of this. It then updates the integer-keyed properties and the length property as needed.

const arrayLike = {
  length: 3,
  unrelated: "foo",
  0: 5,
  2: 4,
};
console.log(Array.prototype.splice.call(arrayLike, 0, 1, 2, 3));
// [ 5 ]
console.log(arrayLike);
// { '0': 2, '1': 3, '3': 4, length: 4, unrelated: 'foo' }

• Indexed collections guide
• Array
• Array.prototype.concat()
• Array.prototype.push()
• Array.prototype.pop()
• Array.prototype.shift()
• Array.prototype.slice()
• Array.prototype.toSpliced()
• Array.prototype.unshift()