Array.prototype.splice()

  • Revision slug: Web/JavaScript/Reference/Global_Objects/Array/splice
  • Revision title: Array.prototype.splice()
  • Revision id: 510357
  • Created:
  • Creator: nisargshah95
  • Is current revision? No
  • Comment

Revision Content

{{JSRef("Global_Objects", "Array")}}

Summary

The splice() method changes the content of an array, adding new elements while removing old elements.

Syntax

array.splice(index , howMany[, element1[, ...[, elementN]]])

array.splice(index) // SpiderMonkey/Firefox extension

Parameters

index
Index at which to start changing the array. If greater than the length of the array, no elements will be added or removed.  If negative, will begin that many elements from the end.
howMany
An integer indicating the number of old array elements to remove. If howMany is 0, no elements are removed. In this case, you should specify at least one new element. If howMany is greater than the number of elements left in the array starting at index, then all of the elements through the end of the array will be deleted.  If no howMany parameter is specified (second syntax above, which is a SpiderMonkey extension), all elements after index are removed.
element1, ..., elementN
The elements to add to the array. If you don't specify any elements, splice simply removes elements from the array.

Returns

An array containing the removed elements. If only one element is removed, an array of one element is returned. If no elements are removed, an empty array is returned.

Description

If you specify a different number of elements to insert than the number you're removing, the array will have a different length at the end of the call.

Examples

Example: Using splice

The following script illustrate the use of splice:

var myFish = ["angel", "clown", "mandarin", "surgeon"];

//removes 0 elements from index 2, and inserts "drum"
var removed = myFish.splice(2, 0, "drum");
//myFish is ["angel", "clown", "drum", "mandarin", "surgeon"]
//removed is [], no elements removed

//removes 1 element from index 3
removed = myFish.splice(3, 1);
//myFish is ["angel", "clown", "drum", "surgeon"]
//removed is ["mandarin"]

//removes 1 element from index 2, and inserts "trumpet"
removed = myFish.splice(2, 1, "trumpet");
//myFish is ["angel", "clown", "trumpet", "surgeon"]
//removed is ["drum"]

//removes 2 elements from index 0, and inserts "parrot", "anemone" and "blue"
removed = myFish.splice(0, 2, "parrot", "anemone", "blue");
//myFish is ["parrot", "anemone", "blue", "trumpet", "surgeon"]
//removed is ["angel", "clown"]

//removes 2 elements from index 3
removed = myFish.splice(3, Number.MAX_VALUE);
//myFish is ["parrot", "anemone", "blue"]
//removed is ["trumpet", "surgeon"]

Specifications

Specification Status Comment
ECMAScript 3rd Edition Standard Initial definition.
Implemented in JavaScript 1.2
{{SpecName('ES5.1', '#sec-15.4.4.12', 'Array.prototype.splice')}} {{Spec2('ES5.1')}}  
{{SpecName('ES6', '#sec-array.prototype.splice', 'Array.prototype.splice')}} {{Spec2('ES6')}}  

Browser compatibility

{{CompatibilityTable}}
Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 1.0 {{CompatGeckoDesktop("1.7")}} 5.5 {{CompatVersionUnknown}} {{CompatVersionUnknown}}
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support {{CompatVersionUnknown}} {{CompatVersionUnknown}} {{CompatVersionUnknown}} {{CompatVersionUnknown}} {{CompatVersionUnknown}} {{CompatVersionUnknown}}

Backward compatibility

The splice method returns the element removed, if only one element is removed (howMany parameter is 1); otherwise, the method returns an array containing the removed elements. Note that the last browser to use JavaScript 1.2 was Netscape Navigator 4, so you can depend on splice always returning an array.

See also

  • {{jsxref("Array.push", "push")}} / {{jsxref("Array.pop", "pop")}} - add/remove elements from the end of the array;
  • {{jsxref("Array.unshift", "unshift")}} / {{jsxref("Array.shift", "shift")}} - add/remove elements from the beginning of the array;
  • {{jsxref("Array.concat", "concat")}} - returns a new array comprised of this array joined with other array(s) and/or value(s).

Revision Source

<div>
 {{JSRef("Global_Objects", "Array")}}</div>
<h2 id="Summary">Summary</h2>
<p>The <code><strong>splice()</strong></code> method changes the content of an array, adding new elements while removing old elements.</p>
<h2 id="Syntax">Syntax</h2>
<pre class="syntaxbox">
<code><em>array</em>.splice(<em>index</em> ,<em> howMany</em>[<em>,</em><em> element1</em>[, ...[, <em>elementN</em>]]])</code>

<code><em>array</em>.splice(<em>index</em>) // SpiderMonkey/Firefox extension</code></pre>
<h3 id="Parameters">Parameters</h3>
<dl>
 <dt>
  <code>index</code></dt>
 <dd>
  Index at which to start changing the array. If greater than the length of the array, no elements will be added or removed.&nbsp; If negative, will begin that many elements from the end.</dd>
</dl>
<dl>
 <dt>
  <code>howMany</code></dt>
 <dd>
  An integer indicating the number of old array elements to remove. If <code>howMany</code> is 0, no elements are removed. In this case, you should specify at least one new element. If <code>howMany</code> is greater than the number of elements left in the array starting at <code>index</code>, then all of the elements through the end of the array will be deleted.&nbsp; If no <code>howMany</code> parameter is specified (second syntax above, which is a SpiderMonkey extension), all elements after <code>index</code> are removed.</dd>
</dl>
<dl>
 <dt>
  <code>element1, ..., element<em>N</em></code></dt>
 <dd>
  The elements to add to the array. If you don't specify any elements, <code>splice</code> simply removes elements from the array.</dd>
</dl>
<h3 id="Returns">Returns</h3>
<p>An array containing the removed elements. If only one element is removed, an array of one element is returned. If no elements are removed, an empty array is returned.</p>
<h2 id="Description">Description</h2>
<p>If you specify a different number of elements to insert than the number you're removing, the array will have a different length at the end of the call.</p>
<h2 id="Examples">Examples</h2>
<h3 id="Example.3A_Using_splice">Example: Using <code>splice</code></h3>
<p>The following script illustrate the use of splice:</p>
<pre class="brush: js">
var myFish = ["angel", "clown", "mandarin", "surgeon"];

//removes 0 elements from index 2, and inserts "drum"
var removed = myFish.splice(2, 0, "drum");
//myFish is ["angel", "clown", "drum", "mandarin", "surgeon"]
//removed is [], no elements removed

//removes 1 element from index 3
removed = myFish.splice(3, 1);
//myFish is ["angel", "clown", "drum", "surgeon"]
//removed is ["mandarin"]

//removes 1 element from index 2, and inserts "trumpet"
removed = myFish.splice(2, 1, "trumpet");
//myFish is ["angel", "clown", "trumpet", "surgeon"]
//removed is ["drum"]

//removes 2 elements from index 0, and inserts "parrot", "anemone" and "blue"
removed = myFish.splice(0, 2, "parrot", "anemone", "blue");
//myFish is ["parrot", "anemone", "blue", "trumpet", "surgeon"]
//removed is ["angel", "clown"]

//removes 2 elements from index 3
removed = myFish.splice(3, Number.MAX_VALUE);
//myFish is ["parrot", "anemone", "blue"]
//removed is ["trumpet", "surgeon"]</pre>
<h2 id="Specifications">Specifications</h2>
<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>ECMAScript 3rd Edition</td>
   <td>Standard</td>
   <td>Initial definition.<br />
    Implemented in JavaScript 1.2</td>
  </tr>
  <tr>
   <td>{{SpecName('ES5.1', '#sec-15.4.4.12', 'Array.prototype.splice')}}</td>
   <td>{{Spec2('ES5.1')}}</td>
   <td>&nbsp;</td>
  </tr>
  <tr>
   <td>{{SpecName('ES6', '#sec-array.prototype.splice', 'Array.prototype.splice')}}</td>
   <td>{{Spec2('ES6')}}</td>
   <td>&nbsp;</td>
  </tr>
 </tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<div>
 {{CompatibilityTable}}</div>
<div id="compat-desktop">
 <table class="compat-table">
  <tbody>
   <tr>
    <th>Feature</th>
    <th>Chrome</th>
    <th>Firefox (Gecko)</th>
    <th>Internet Explorer</th>
    <th>Opera</th>
    <th>Safari</th>
   </tr>
   <tr>
    <td>Basic support</td>
    <td>1.0</td>
    <td>{{CompatGeckoDesktop("1.7")}}</td>
    <td>5.5</td>
    <td>{{CompatVersionUnknown}}</td>
    <td>{{CompatVersionUnknown}}</td>
   </tr>
  </tbody>
 </table>
</div>
<div id="compat-mobile">
 <table class="compat-table">
  <tbody>
   <tr>
    <th>Feature</th>
    <th>Android</th>
    <th>Chrome for Android</th>
    <th>Firefox Mobile (Gecko)</th>
    <th>IE Mobile</th>
    <th>Opera Mobile</th>
    <th>Safari Mobile</th>
   </tr>
   <tr>
    <td>Basic support</td>
    <td>{{CompatVersionUnknown}}</td>
    <td>{{CompatVersionUnknown}}</td>
    <td>{{CompatVersionUnknown}}</td>
    <td>{{CompatVersionUnknown}}</td>
    <td>{{CompatVersionUnknown}}</td>
    <td>{{CompatVersionUnknown}}</td>
   </tr>
  </tbody>
 </table>
</div>
<h3 id="Backward_compatibility">Backward compatibility</h3>
<p>The <code>splice</code> method returns the element removed, if only one element is removed (<code>howMany</code> parameter is 1); otherwise, the method returns an array containing the removed elements. Note that the last browser to use JavaScript 1.2 was Netscape Navigator 4, so you can depend on <code>splice</code> always returning an array.</p>
<h2 id="See_also" name="See_also">See also</h2>
<ul>
 <li>{{jsxref("Array.push", "push")}} / {{jsxref("Array.pop", "pop")}} - add/remove elements from the end of the array;</li>
 <li>{{jsxref("Array.unshift", "unshift")}} / {{jsxref("Array.shift", "shift")}} - add/remove elements from the beginning of the array;</li>
 <li>{{jsxref("Array.concat", "concat")}} - returns a new array comprised of this array joined with other array(s) and/or value(s).</li>
</ul>
Revert to this revision