Node.insertBefore()

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

Syntax

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

If referenceNode is null, the newNode is inserted at the end of the list of child nodes.

Note that referenceNode is not an optional parameter -- you must explicitly pass a Node or null. Failing to provide it or passing invalid values may behave differently in different browser versions.

The returned value is the inserted 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("childElement").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 ]
</script>

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

Specifications

See also

• Node.removeChild()
• Node.replaceChild()
• Node.appendChild()
• Node.hasChildNodes()