replaceWith() is a DOM method that replaces the current node with one or more nodes or strings. It is simpler than replaceChild() because you call it directly on the element you want to replace.
Use replaceWith() when you already selected the element that should be removed from the DOM and replaced by another element, text node, or combination of nodes.
Environment: Node.js v20.18.2. After each runnable snippet, the following paragraph states the expected console output (order and values).
JavaScript replaceWith Syntax
node.replaceWith(...nodesOrStrings)Each argument can be a Node or a string. Strings are inserted as text nodes, not parsed as HTML.
function replaceWithMock(node, ...items) {
node.replacedWith = items.join("|");
return node.replacedWith;
}
console.log("replacewith:", replaceWithMock({}, "new heading", "button"));You should see one line logging replacewith: new heading|button.
Method 1: Replace an Element with Another Element
const oldHeading = document.querySelector("h1");
const newHeading = document.createElement("h2");
newHeading.textContent = "Updated heading";
oldHeading?.replaceWith(newHeading);This removes the original h1 and inserts the new h2 in the same location.
Method 2: Replace an Element with Text
const status = document.querySelector(".status");
status?.replaceWith("Done");The replacement is inserted as text. It is not parsed as HTML.
Method 3: Replace an Element with Multiple Nodes
const target = document.querySelector("#target");
const strong = document.createElement("strong");
strong.textContent = "Saved";
target?.replaceWith(strong, " successfully");This replaces one node with an element followed by text.
Method 4: replaceWith vs replaceChild
oldNode.replaceWith(newNode);
parentNode.replaceChild(newNode, oldNode);Use replaceWith() for readability in modern code. Use replaceChild() when parent-based control is required.
Common Questions About replaceWith in JavaScript
What does replaceWith do?
It removes the current node and inserts the provided node or string values in its place.
Does replaceWith accept HTML strings?
It accepts strings, but they are inserted as text nodes. They are not parsed as HTML elements.
Is replaceWith the same as jQuery replaceWith?
They solve a similar problem, but native JavaScript replaceWith() is a DOM method and does not use jQuery collections or jQuery-specific behavior.
Summary
Use JavaScript replaceWith() to replace a DOM node directly with another node, text, or multiple replacement values. It is concise for modern DOM code because it avoids manually calling the parent node. Use replaceChild() when your code is organized around parent-child node operations.
