JavaScript Node replaceChild() Method

What You’ll Learn

The Node.replaceChild() method swaps one child for another on a parent. Learn the unusual new before old argument order, what happens when the new node is already in the tree, how the return value is the old child, and how this pairs with removeChild() and appendChild().

Introduction

Sometimes you do not only remove a child—you put something else in the same spot. parent.replaceChild(newChild, oldChild) does that in one step: the old child leaves, the new child takes its place among the siblings.

MDN highlights two beginner traps: the parameter order is new first, old second, and if newChild already lives elsewhere in the document, the browser moves it (it is removed from the old location first).

Understanding replaceChild()

Call it on the parent. Pass the node that should appear, then the child that should leave. Get the old child back as the return value.

• Swap — newChild takes oldChild’s place.
• Order — (newChild, oldChild)—new before old.
• Return — the replaced node (same as oldChild).
• Move — an already-attached newChild is relocated, not cloned.

📝 Syntax

const replaced = parentNode.replaceChild(newChild, oldChild);

Parameters

• newChild — The node that will replace oldChild. Warning (MDN): if it is already in the DOM, it is removed from its current position first.
• oldChild — The child of this parent that will be replaced.

Return value

The replaced Node—the same object as oldChild.

Exceptions

• NotFoundError — oldChild is not a child of the node you called.
• HierarchyRequestError — the swap would break DOM rules (for example a cycle, wrong node type, or invalid document structure).

⚖️ replaceChild() vs Element.replaceWith()

Examples Gallery

Examples follow MDN Node.replaceChild() ideas. Use View Output or Try It Yourself.

const parentDiv = document.createElement("div");
const sp2 = document.createElement("span");
sp2.id = "childSpan";
sp2.textContent = "foo bar";
parentDiv.appendChild(sp2);

const sp1 = document.createElement("span");
sp1.id = "newSpan";
sp1.appendChild(document.createTextNode("new replacement span element."));

parentDiv.replaceChild(sp1, sp2);

console.log(parentDiv.firstChild.id);          // "newSpan"
console.log(parentDiv.firstChild.textContent); // "new replacement span element."
console.log(parentDiv.contains(sp2));          // false

newSpan
new replacement span element.
false

const list = document.createElement("ul");
const oldItem = document.createElement("li");
oldItem.textContent = "Old";
list.appendChild(oldItem);

const newItem = document.createElement("li");
newItem.textContent = "New";

// Correct: new first, old second
list.replaceChild(newItem, oldItem);

console.log(list.firstChild.textContent); // "New"
console.log(list.childNodes.length);      // 1

New
1

const a = document.createElement("div");
const b = document.createElement("div");
const mover = document.createElement("p");
mover.textContent = "Mover";
const target = document.createElement("span");
target.textContent = "Target";

a.appendChild(mover);
b.appendChild(target);

b.replaceChild(mover, target);

console.log(a.contains(mover)); // false (moved away)
console.log(b.firstChild.textContent); // "Mover"
console.log(b.contains(target)); // false

false
Mover
false

const box = document.createElement("div");
const oldNode = document.createElement("em");
oldNode.textContent = "Old";
box.appendChild(oldNode);

const neu = document.createElement("strong");
neu.textContent = "New";

const replaced = box.replaceChild(neu, oldNode);

console.log(replaced === oldNode);   // true
console.log(replaced.textContent);   // "Old"
console.log(box.firstChild.tagName); // "STRONG"

true
Old
STRONG

const parent = document.createElement("div");
const other = document.createElement("div");
const orphan = document.createElement("span");
other.appendChild(orphan);

const neu = document.createElement("b");

try {
  parent.replaceChild(neu, orphan); // orphan is not parent's child
} catch (err) {
  console.log(err.name); // "NotFoundError"
}

NotFoundError

🚀 Common Use Cases

• Swapping a placeholder element for real content in the same position.
• Updating a list item without rebuilding the whole list.
• Moving a node from one parent into another child slot via replacement.
• Teaching classic DOM mutation next to appendChild / removeChild.
• Keeping a reference to the old child for undo or history UI.

🔧 How It Works

📝 Notes

• Baseline Widely available (MDN, since July 2015).
• Not Deprecated, Experimental, or Non-standard — no status banner required.
• Parameter order is easy to reverse—double-check (new, old).
• Related: selectstart, removeChild(), appendChild(), insertBefore(), cloneNode(), JavaScript hub.

💡 Best Practices