JavaScript - splice() method

revision:


Category : array

The splice() method changes the contents of an array by removing or replacing existing elements and/or adding new elements in place. It adds and/or removes array elements. It overwrites the original array.

To create a new array with a segment removed and/or replaced without mutating the original array, use toSpliced(). To access part of an array without modifying it, see slice().

Syntax :

        array.splice(start)
        array.splice(start, deleteCount)
        array.splice(start, deleteCount, item1)
        array.splice(start, deleteCount, item1, item2, itemN)
        array.splice(index, howmany, item1, ....., itemX)
    

Parameters:

start, index : required; 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 "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.

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.

Examples:

            const months = ['Jan', 'March', 'April', 'June'];
            months.splice(1, 0, 'Feb');
            // Inserts at index 1
            console.log(months);
            // Expected output: Array ["Jan", "Feb", "March", "April", "June"]
             months.splice(4, 1, 'May');
            // Replaces 1 element at index 4
            console.log(months);
            // Expected output: Array ["Jan", "Feb", "March", "April", "May"]
        

Practical examples

example: remove 0 (zero) elements before index 2, and insert "drum".

code:
                    <div>
                        <p id="splice-1"></p>
                        <p id="splice-2"></p>
                        <p id="splice-3"></p>
                    </div>
                    <script>
                        const myFish = ["angel", "clown", "mandarin", "sturgeon"];
                        document.getElementById("splice-1").innerHTML = "array fish: " + myFish;
                        const removed = myFish.splice(2, 0, "drum");
                        document.getElementById("splice-2").innerHTML = "array fish: " + myFish;
                        document.getElementById("splice-2").innerHTML = "removed fish: " + removed;
                        // myFish is ["angel", "clown", "drum", "mandarin", "sturgeon"]
                        // removed is [], no elements removed
                    </script>
                

example: remove 1 element at index 3.

code:
                    <div>
                        <p id="splice-4"></p>
                        <p id="splice-5"></p>
                        <p id="splice-6"></p>
                    </div>
                    <script>
                        const myFishes = ["angel", "clown", "drum", "mandarin", "sturgeon"];
                        document.getElementById("splice-4").innerHTML = "array fishes: " + myFishes;
                        const beenRemoved = myFishes.splice(3, 1);
                        document.getElementById("splice-5").innerHTML = "array fishes: " + myFishes;
                        document.getElementById("splice-6").innerHTML = "removed fishes: " + beenRemoved;
                        // myFish is ["angel", "clown", "drum", "sturgeon"]
                        // removed is ["mandarin"]
                    </script>
                

example: at position 2, add 2 elements; at position 2, remove 2 items.

code:
                    <div>
                        <p id="splice-7"></p>
                        <p id="splice-8"></p>
                        <p id="splice-9"></p>
                        <p id="splice-10"></p>
                    </div>
                    <script>
                        const fruits = [" Banana", " Orange", " Apple", " Mango"];
                        document.getElementById("splice-7").innerHTML = " original array : " + fruits;
                        // At position 2, add 2 elements: 
                        fruits.splice(2, 0, " Lemon", " Kiwi");
                        document.getElementById("splice-8").innerHTML = "new array : " + fruits;
                        fruits.splice(2, 2);
                        document.getElementById("splice-9").innerHTML = "new array : " + fruits;
                    </script>