Node: replaceChild() method
DOM
DOM
The replaceChild() method of the Node interface replaces a child node within the given (parent) node.
Syntax
replaceChild(newChild, oldChild)
Parameters
newChild- : The new node to replace
oldChild. > [!WARNING] > If the new node is already present somewhere else in the DOM, it is first removed from that position. oldChild- : The child to be replaced.
[!NOTE] The parameter order, new before old, is unusual.
Element.replaceWith(), applying only to nodes that are elements, may be easier to read and use.
Return value
The replaced Node. This is the same node as oldChild.
Exceptions
HierarchyRequestErrorDOMException- : Thrown when the constraints of the DOM tree are violated, that is if one of the following cases occurs:
- If the parent of
oldChildis not a Document, DocumentFragment, or an Element. - If the replacement of
oldChildbynewChildwould lead to a cycle, that is ifnewChildis an ancestor of the node. - If
newChildis not a DocumentFragment, a DocumentType, an Element, or a CharacterData. - If the current node is a Text, and its parent is a Document.
- If the current node is a DocumentType and its parent is not a Document, as a doctype should always be a direct descendant of a document.
- If the parent of the node is a Document and
newChildis a DocumentFragment with more than one Element child, or that has a Text child. - If the replacement of
oldChildbynewChildwould lead to Document with more than one Element as child. - If the replacement of
oldChildbynewChildwould lead to the presence of an Element node before a DocumentType node.
- If the parent of
NotFoundErrorDOMException- : Thrown if the parent of
oldChildis not the current node.
Example
// Given:
// <div>
// <span id="childSpan">foo bar</span>
// </div>
// Create an empty element node
// without an ID, any attributes, or any content
const sp1 = document.createElement("span");
// Give it an id attribute called 'newSpan'
sp1.id = "newSpan";
// Create some content for the new element.
const sp1Content = document.createTextNode("new replacement span element.");
// Apply that content to the new element
sp1.appendChild(sp1Content);
// Build a reference to the existing node to be replaced
const sp2 = document.getElementById("childSpan");
const parentDiv = sp2.parentNode;
// Replace existing node sp2 with the new span element sp1
parentDiv.replaceChild(sp1, sp2);
// Result:
// <div>
// <span id="newSpan">new replacement span element.</span>
// </div>
Specifications
Browser compatibility
See also
- Node.removeChild
- Element.replaceWith