Availability

DOM Level 1 Core

Synopsis

Node replaceChild(Node newChild, 
                  Node oldChild) 
    throws DOMException;

Arguments

newChild

The replacement node.

oldChild

The node to be replaced.

Returns

The node that was removed from the document and replaced.

Throws

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

HIERARCHY_REQUEST_ERR

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

WRONG_DOCUMENT_ERR

newChild and this node have different values for ownerDocument.

NO_MODIFICATION_ALLOWED_ERR

This node is read-only and does not allow replacement, or newChild is the child of a node that does not allow removals.

NOT_FOUND_ERR

oldChild is not a child of this node.

Description

This method replaces one node of the document tree with another. oldChild is the node to be replaced, and must be a child of this node. newChild is the node that takes its place in the childNodes[] array of this node.

If newChild is already part of the document, it is first removed from the document before being reinserted at its new position. If newChild is a DocumentFragment, it is not inserted itself; instead each of its children is inserted, in order, at the position formerly occupied by oldChild.

Example

The following code replaces a node n with a <b> element and then inserts the replaced node into the <b> element, which reparents the node and makes it appear in bold:

// Get the first child node of the first paragraph in the document
var n = document.getElementsByTagName("p")[0].firstChild;
var b = document.createElement("b");  // Create a <b> element
n.parentNode.replaceChild(b, n);      // Replace the node with <b>
b.appendChild(n);                     // Reinsert the node as a child of <b>

See Also

Node.appendChild( ), Node.insertBefore( ), Node.removeChild( )