Node.insertBefore()

The Node.insertBefore() method inserts the specified node before a reference node as a child of the current node.

Syntax

var insertedNode = parentNode.insertBefore(newNode, referenceNode);

In Mozilla Firefox, if referenceNode is null, newNode is inserted at the end of the list of child nodes.  If the referenceNode is of [ Type ] "undefined" ( this kind of argument is String ) will be throw, in all of the browser ( IE, Chrome and Mozilla ) a "Type Error: Invalid Argument" since the the function insertBefore accept as second argument a [ Type ] Node.

Example

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

<script>
//Create the new node to insert
var newNode = document.createElement("span");

//Get a reference to the parent node
var parentDiv = document.getElementById("parentElement").parentNode;

//Begin test case [ 1 ] : Exist a childElement --> All working correctly
var sp2 = document.getElementById("childElement");
parentDiv.insertBefore(newNode,sp2);
//End test case [ 1 ]

//Begin test case [ 2 ] : childElement is of Type undefined 
var sp2 = undefined; //Not exist a node of id "childElement"
parentDiv.insertBefore(newNode,sp2); //implicit dynamic cast to type Node
//End test case [ 2 ]

//Begin test case [ 3 ] : childElement is of Type "undefined" ( string )
var sp2 = "undefined"; //Not exist a node of id "childElement"
parentDiv.insertBefore(newNode,sp2); //Generate "Type Error: Invalid Argument" 
//End test case [ 3 ]

• insertedNode The node being inserted, that is newNode
• parentNode The parent of the newly inserted node.
• newNode The node to insert.
• referenceNode The node before which newNode 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 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

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

Specification

• insertBefore