Node.insertBefore

  • Revision slug: Web/API/Node.insertBefore
  • Revision title: Node.insertBefore
  • Revision id: 409259
  • Created:
  • Creator: ethertank
  • Is current revision? No
  • Comment

Revision Content

{{DomRef()}}

Summary

Inserts the specified node before a reference element as a child of the current node.

Syntax

var insertedElement = parentElement.insertBefore(newElement, referenceElement);

If referenceElement is null, newElement is inserted at the end of the list of child nodes.

  • insertedElement The node being inserted, that is newElement
  • parentElement The parent of the newly inserted node.
  • newElement The node to insert.
  • referenceElement The node before which newElement is inserted.

Example

<div id="parentElement">
  <span id="childElement">foo bar</span>
</div>

<script>
// Create a new, plain <span> element
var sp1 = document.createElement("span");

// Get a reference to the element, before we want to insert the element
var sp2 = document.getElementById("childElement");
// Get a reference to the parent element
var parentDiv = sp2.parentNode;

// Insert the new element into the DOM before sp2
parentDiv.insertBefore(sp1, sp2);
</script>

There is no insertAfter method. It can be emulated by combining the insertBefore method with and nextSibling.

In the previous example, sp1 could be inserted after sp2 using:

parentDiv.insertBefore(sp1, sp2.nextSibling);

If sp2 does not have a next sibling, then it must be the last child — sp2.nextSibling returns null, and sp1 is inserted at the end of the child node list (immediately after sp2).

Example 2

Insert an element before the first child element, using the firstChild property.

// Get a reference to the element in which we want to insert a new node
var parentElement = document.getElementById('parentElement');
// Get a reference to the first child
var theFirstChild = parentElement.firstChild;

// Create a new element
var newElement = document.createElement("div");

// Insert the new element before the first child
parentElement.insertBefore(newElement, theFirstChild);

When the element does not have a first child, then firstChild is null. The element is still appended to the parent, after the last child. Since the parent element did not have a first child, it did not have a last child either. Consequently, the new element is the only element, after insertion.

Browser compatibility

{{CompatibilityTable()}}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 1.0 {{CompatVersionUnknown}} {{CompatVersionUnknown}} {{CompatVersionUnknown}} {{CompatVersionUnknown}}
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support {{CompatUnknown}} {{CompatUnknown}} {{CompatUnknown}} {{CompatUnknown}} {{CompatUnknown}}

Specification

Revision Source

<div>
  {{DomRef()}}</div>
<h2 id="Summary" name="Summary">Summary</h2>
<p>Inserts the specified node before a reference element as a child of the current node.</p>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<pre class="syntaxbox">
var <em>insertedElement</em> = <em>parentElement</em>.insertBefore(<em>newElement</em>, <em>referenceElement</em>);
</pre>
<p>If <var>referenceElement</var> is <code>null</code>, <var>newElement</var> is inserted at the end of the list of child nodes.</p>
<ul>
  <li><code>insertedElement</code> The node being inserted, that is <code>newElement</code></li>
  <li><code>parentElement</code> The parent of the newly inserted node.</li>
  <li><code>newElement</code> The node to insert.</li>
  <li><code>referenceElement</code> The node before which <code>newElement</code> is inserted.</li>
</ul>
<h2 id="Example" name="Example">Example</h2>
<pre class="brush:html">
&lt;div id="parentElement"&gt;
  &lt;span id="childElement"&gt;foo bar&lt;/span&gt;
&lt;/div&gt;

&lt;script&gt;
// Create a new, plain &lt;span&gt; element
var sp1 = document.createElement("span");

// Get a reference to the element, before we want to insert the element
var sp2 = document.getElementById("childElement");
// Get a reference to the parent element
var parentDiv = sp2.parentNode;

// Insert the new element into the DOM before sp2
parentDiv.insertBefore(sp1, sp2);
&lt;/script&gt;
</pre>
<p>There is no <code>insertAfter</code> method. It can be emulated by combining the <code>insertBefore</code> method with and <code><a href="/en-US/docs/DOM/Node.nextSibling" title="DOM/Node.nextSibling">nextSibling</a></code>.</p>
<p>In the previous example, <code>sp1</code> could be inserted after <code>sp2</code> using:</p>
<pre>
<code>parentDiv.insertBefore(sp1, sp2.nextSibling);</code></pre>
<p>If <code>sp2</code> does not have a next sibling, then it must be the last child — <code>sp2.nextSibling</code> returns <code>null</code>, and <code>sp1</code> is inserted at the end of the child node list (immediately after <code>sp2</code>).</p>
<h2 id="Example2" name="Example2">Example 2</h2>
<p>Insert an element before the first child element, using the <a href="/en-US/docs/DOM/Node.firstChild" title="Node.firstChild">firstChild</a> property.</p>
<pre class="brush:js">
// Get a reference to the element in which we want to insert a new node
var parentElement = document.getElementById('parentElement');
// Get a reference to the first child
var theFirstChild = parentElement.firstChild;

// Create a new element
var newElement = document.createElement("div");

// Insert the new element before the first child
parentElement.insertBefore(newElement, theFirstChild);
</pre>
<p>When the element does not have a first child, then <code>firstChild</code> is <code>null</code>. The element is still appended to the parent, after the last child. Since the parent element did not have a first child, it did not have a last child either. Consequently, the new element is the only element, after insertion.</p>
<h2 id="Browser_Compatibility" name="Browser_Compatibility">Browser compatibility</h2>
<p>{{CompatibilityTable()}}</p>
<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 (WebKit)</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>1.0</td>
        <td>{{CompatVersionUnknown}}</td>
        <td>{{CompatVersionUnknown}}</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>Firefox Mobile (Gecko)</th>
        <th>IE Phone</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>{{CompatUnknown}}</td>
        <td>{{CompatUnknown}}</td>
        <td>{{CompatUnknown}}</td>
        <td>{{CompatUnknown}}</td>
        <td>{{CompatUnknown}}</td>
      </tr>
    </tbody>
  </table>
</div>

<h2 id="Specification" name="Specification">Specification</h2>
<ul>
  <li><a href="http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/core.html#ID-952280727">insertBefore</a></li>
</ul>
Revert to this revision