Availability

DOM Level 1 Core

Synopsis

Node insertBefore(Node newChild, 
                  Node refChild) 
    throws DOMException;

Arguments

newChild

The node to be inserted into the tree. If it is a DocumentFragment, its children are inserted instead.

refChild

The child of this node before which newChild is to be inserted. If this argument is null, newChild is inserted as the last child of this node.

Returns

The node that was inserted.

Throws

This method may throw a DOMException with the following code values:

HIERARCHY_REQUEST_ERR

This node does not support children, or it does not allow children of the specified type, or newChild is an ancestor of this node (or is this node itself ).

WRONG_DOCUMENT_ERR

The ownerDocument property of newChild and this node are different.

NO_MODIFICATION_ALLOWED_ERR

This node is read-only and does not allow insertions or the parent of newChild is read-only and does not allow deletions.

NOT_FOUND_ERR

refChild is not a child of this node.

Description

This method inserts the node newChild into the document tree as a child of this node. The new node is positioned within this node's childNodes[] array so that it comes immediately before the refChild node. If refChild is null, newChild is inserted at the end of childNodes[], just as with the appendChild( ) method. Note that it is illegal to call this method with a refChild that is not a child of this node.

If newChild is already in the document tree, it is removed from the tree and then reinserted at its new position. If newChild is a DocumentFragment node, it is not inserted itself; instead, each of its children is inserted, in order, at the specified location.

Example

The following function inserts a new paragraph at the beginning of a document:

function insertMessage(message) {
    var paragraph = document.createElement("p");  // Create a <p> Element
    var text = document.createTextNode(message);  // Create a Text node
    paragraph.appendChild(text);                  // Add text to the paragraph
    // Now insert the paragraph before the first child of the body
    document.body.insertBefore(paragraph, document.body.firstChild)
}

See Also

Node.appendChild( ), Node.removeChild( ), Node.replaceChild( )