JavaScript Element replaceChildren() Method

What You’ll Learn

Element.replaceChildren() is an instance method from the ParentNode API. It replaces all existing children with a new set of nodes or strings. Learn how to empty a container, transfer nodes between lists (MDN party food demo), how it compares to append() and innerHTML, and five try-it labs.

Introduction

Old patterns clear children with loops or innerHTML = "". replaceChildren() is the modern ParentNode helper: swap the entire child list in one call—or empty the element by calling it with no arguments (MDN).

Like append() and prepend(), strings become Text nodes automatically.

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

Understanding the replaceChildren() Method

Calling el.replaceChildren(...nodes) removes every current child of el, then inserts the arguments as the new child list in order.

• It is an instance method on Element (ParentNode mixin).
• Arguments can be Node objects or strings (as Text).
• No arguments → element is emptied (MDN).
• Existing nodes in the document are moved, not cloned.
• Return value is undefined (MDN).
• Can throw when node tree constraints are violated (MDN).

📝 Syntax

General forms of Element.replaceChildren (MDN):

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

Parameters

• param1, …, paramN (optional) — a set of Node objects or strings to replace the element’s existing children with (MDN). If omitted, all children are removed.

Return value

None (undefined) (MDN).

Exceptions

• Thrown when the constraints of the node tree are violated (MDN).

Common patterns

// Empty all children (MDN)
myNode.replaceChildren();

// Replace with new content
container.replaceChildren(heading, paragraph, " ");

// Transfer nodes between parents (MDN party food pattern)
yesSelect.replaceChildren(...selected, ...existing);

Examples Gallery

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

const myNode = document.getElementById("box");
myNode.replaceChildren();

console.log(myNode.childNodes.length); // 0

0

const container = document.getElementById("box");
const heading = document.createElement("h2");
heading.textContent = "Updated";
const note = document.createElement("p");
note.textContent = "Fresh content";

container.replaceChildren(heading, note);

console.log(container.children.length); // 2

2

const noSelect = document.getElementById("no");
const yesSelect = document.getElementById("yes");

const selected = document.querySelectorAll("#no option:checked");
const existing = document.querySelectorAll("#yes option");

yesSelect.replaceChildren(...selected, ...existing);

2 options in yes list

const div = document.createElement("div");
div.append(document.createElement("p")); // old child

div.replaceChildren("Hello, world!");

console.log(div.textContent); // "Hello, world!"

Hello, world!

const box = document.getElementById("box");
const extra = document.createElement("span");
extra.textContent = "new";

box.append(extra);
console.log(box.childNodes.length); // 3 (kept old + added)

box.replaceChildren(extra);
console.log(box.childNodes.length); // 1 (only extra)

3
1

🚀 Common Use Cases

• Emptying modal bodies, lists, or panels before re-rendering content.
• Transferring selected options between dual-list UIs (MDN party food demo).
• Replacing a container’s children with freshly built nodes in one call.
• Avoiding while (el.firstChild) el.removeChild(...) loops.
• Teaching ParentNode helpers alongside append() and prepend().
• Pairing with remove() when you need to delete the element itself.

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available since October 2020).
• replaceChildren() replaces all children—not siblings.
• Return value is always undefined (MDN).
• No arguments empties the element (MDN).
• Invalid hierarchy can throw per MDN node tree constraints.
• Related: append(), prepend(), children, JavaScript hub.

💡 Best Practices