JavaScript Element replaceWith() Method

What You’ll Learn

Element.replaceWith() is an instance method from the ChildNode API. It replaces the element itself in its parent’s child list with new nodes or strings. Learn the MDN p → span swap, how it differs from replaceChildren(), and five try-it labs.

Introduction

Older DOM code often used parent.replaceChild(newNode, oldNode) to swap one element for another. replaceWith() expresses the same idea on the element being removed: call it on the node you want gone, and pass what should take its place.

You can pass elements, other nodes, or plain strings. Strings become Text nodes automatically. After the call, the original element is no longer in the document.

This page is part of JavaScript Element. Related: remove(), after().

Understanding the replaceWith() Method

Calling el.replaceWith(...nodes) removes el from its parent and inserts the new nodes in the same position among siblings.

• It is an instance method on Element (ChildNode mixin).
• Arguments can be Node objects or strings (as Text).
• Multiple arguments insert in the order you pass them.
• The element you call replaceWith on is removed from the DOM.
• Return value is undefined (MDN).
• MDN: replaceWith is unscopable—unavailable inside with.

📝 Syntax

General forms of Element.replaceWith (MDN):

replaceWith(param1)
replaceWith(param1, param2)
replaceWith(param1, param2, /* …, */ paramN)

Parameters

• param1, …, paramN — a set of Node objects or strings to replace this element with (MDN).

Return value

None (undefined) (MDN).

Exceptions

• Thrown when the node cannot be inserted at the specified point in the hierarchy (MDN).

Common patterns

const p = document.querySelector("p");
const span = document.createElement("span");

p.replaceWith(span);           // swap element
p.replaceWith("Upgraded");     // swap for text
p.replaceWith(span, " · ");   // several replacements in order

Examples Gallery

Examples follow MDN Element.replaceWith() patterns. Use View Output or Try It Yourself for each case.

const div = document.createElement("div");
const p = document.createElement("p");
div.appendChild(p);
const span = document.createElement("span");

p.replaceWith(span);

console.log(div.outerHTML);
// "<div><span></span></div>"

<div><span></span></div>

const div = document.createElement("div");
const p = document.createElement("p");
p.textContent = "Old";
div.appendChild(p);

p.replaceWith("Upgraded");

console.log(div.textContent); // "Upgraded"

Upgraded

const div = document.createElement("div");
const old = document.createElement("p");
old.textContent = "Old";
div.appendChild(old);
const span = document.createElement("span");
span.textContent = "New";

old.replaceWith(span, " (updated)");

console.log(div.innerHTML);
// <span>New</span> (updated)

<span>New</span> (updated)

const box = document.getElementById("box");
const inner = document.getElementById("inner");

// replaceWith — removes #inner element itself
// inner.replaceWith(document.createElement("section"));

// replaceChildren — keeps #inner, swaps its kids
inner.replaceChildren("Only text inside");

console.log(box.innerHTML);
// <div id="inner">Only text inside</div>

<div id="inner">Only text inside</div>

const oldBtn = document.getElementById("old-btn");
const newBtn = document.createElement("button");
newBtn.id = "new-btn";
newBtn.textContent = "Continue";
newBtn.type = "button";

oldBtn.replaceWith(newBtn);

console.log(document.getElementById("new-btn") !== null); // true

true

🚀 Common Use Cases

• Swapping an outdated button or card for a freshly built element.
• Replacing a placeholder node with real content after data loads.
• Upgrading a custom element or widget in place without touching the parent.
• Replacing an element with plain text when markup is no longer needed.
• Expressing parent.replaceChild(newNode, oldNode) on the node being removed.
• Teaching the difference between replacing self vs replacing children.

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available since April 2018).
• replaceWith() replaces the element itself, not its children.
• Return value is always undefined.
• Invalid hierarchy can raise HierarchyRequestError.
• MDN: replaceWith is unscopable—unavailable inside a with statement.
• Same ChildNode family: before(), after(), remove(), replaceChildren().
• Related: replaceChild(), children, JavaScript hub.

💡 Best Practices