This article needs a technical review. How you can help.
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 isnewNode
parentNode
The parent of the newly inserted node.newNode
The node to be inserted.referenceNode
The node before whichnewNode
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
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|
Basic support | 1.0 | (Yes) | (Yes) | (Yes) | (Yes) |
Feature | Android | Firefox Mobile (Gecko) | IE Phone | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|
Basic support | ? | ? | ? | ? | ? |
Specifications
Specification | Status | Comment |
---|---|---|
DOM The definition of 'Node.insertBefore' in that specification. |
Living Standard | Fixes errors in the insertion algorithm |
DOM4 The definition of 'Node.insertBefore' in that specification. |
Recommendation | Describes the algorithm in more detail |
Document Object Model (DOM) Level 3 Core Specification The definition of 'Node.insertBefore' in that specification. |
Recommendation | No notable changes |
Document Object Model (DOM) Level 2 Core Specification The definition of 'Node.insertBefore' in that specification. |
Recommendation | No notable changes |
Document Object Model (DOM) Level 1 Specification The definition of 'Node.insertBefore' in that specification. |
Recommendation | Introduced |