Replacing a DOM element in JavaScript means swapping an existing node for a new node or text. The two main native methods are parentNode.replaceChild(newNode, oldNode) and oldNode.replaceWith(newNode). Both update the page, but they are called from different places.
Use replaceWith() for modern, direct replacement. Use replaceChild() when working through the parent node or maintaining older code patterns.
Environment: Node.js v20.18.2. After each runnable snippet, the following paragraph states the expected console output (order and values).
Method 1: Replace an Element with replaceChild()
replaceChild() is called on the parent node.
const oldTitle = document.querySelector("#title");
const newTitle = document.createElement("h2");
newTitle.textContent = "Updated title";
if (oldTitle && oldTitle.parentNode) {
oldTitle.parentNode.replaceChild(newTitle, oldTitle);
}Helper test:
function replaceChildMock(parent, newNode, oldNode) {
parent.child = newNode;
return oldNode;
}
const oldNode = { id: "old" };
const parent = { child: oldNode };
console.log("replacechild:", replaceChildMock(parent, { id: "new" }, oldNode).id + "->" + parent.child.id);You should see one line logging replacechild: old->new.
Method 2: Replace an Element with replaceWith()
replaceWith() is called on the node being replaced.
const oldButton = document.querySelector(".old-button");
const newButton = document.createElement("button");
newButton.textContent = "Save";
oldButton?.replaceWith(newButton);This is concise because you do not need to manually access the parent node.
Method 3: Replace an Element with Text
replaceWith() can receive a string. The browser inserts it as a text node.
const badge = document.querySelector(".badge");
badge?.replaceWith("Completed");Use this when the replacement should be plain text rather than an HTML element.
Method 4: Replace Multiple Nodes
replaceWith() can accept multiple nodes or strings.
const target = document.querySelector("#target");
const heading = document.createElement("h2");
heading.textContent = "Profile";
target?.replaceWith(heading, " loaded");This replaces one node with both an element and text.
Common Questions About Replacing DOM Elements
What is the difference between replaceChild and replaceWith?
replaceChild() is called on the parent and takes (newNode, oldNode). replaceWith() is called on the old node and takes the replacement nodes or strings.
How do I replace HTML content instead of the whole element?
Use element.innerHTML, textContent, or replaceChildren() when the parent element should stay in place.
Should I use replaceChild or replaceWith?
Use replaceWith() for modern code. Use replaceChild() when you already have the parent node or need parent-based control.
Summary
To replace a DOM element in JavaScript, create or select the replacement node, then use replaceWith() on the old element or replaceChild() on its parent. Check that the old element exists before replacing it, and use text replacement only when you want plain text instead of HTML.
