JavaScript: The Definitive Guide, 5th Edition

Name

Node.replaceChild( ): replace a child node with a new node — DOM Level 1 Core

Synopsis

Node replaceChild(NodenewChild,
                  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, 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.

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