Section 25.218. Node.replaceChild( ): replace a child node with a new node

25.218. Node.replaceChild( ): replace a child node with a new node

DOM Level 1 Core

25.218.1. Synopsis

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

25.218.1.1. Arguments

newChild

The replacement node.

oldChild

The node to be replaced.

25.218.1.2. Returns

The node that was removed from the document and replaced.

25.218.1.3. Throws

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

HIERARCHY_REQUEST_ERR

This node does not allow children, 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

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.

25.218.2. 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.

25.218.3. 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> 

25.218.4. See Also

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