document.replaceChildren() is an instance method from the ParentNode API. It replaces every child of the Document with a new set of nodes or strings (see MDN Document: replaceChildren()). Learn MDN’s empty-document pattern, building roots on new Document(), HierarchyRequestError, how it compares to Element.replaceChildren(), and five try-it labs.
01
Kind
Instance method
02
Args
0+ nodes/strings
03
Returns
undefined
04
Empty
No arguments
05
UI tip
Use Element
06
Status
Baseline
Fundamentals
Introduction
Everyday tutorials empty a list with list.replaceChildren() or rebuild a panel with panel.replaceChildren(newHeading, newPara). Those calls use Element.replaceChildren(). Document.replaceChildren() is the same ParentNode method, but the target is the Document node itself — not <body>.
MDN highlights a convenient empty pattern: call document.replaceChildren() with no arguments, then document.children is an empty HTMLCollection.
💡
Beginner tip
Do not call document.replaceChildren() with no args on the live page you are viewing — it removes the page’s root <html>. Practice on new Document(), or use document.body.replaceChildren(...) / el.replaceChildren(...) for UI work.
param1, …, paramN — a set of Node objects or strings to replace the Document’s existing children with. If none are specified, the Document is emptied of all child nodes (MDN).
Return value
None (undefined) (MDN).
Exceptions
HierarchyRequestErrorDOMException — thrown if the constraints of the node tree are violated (MDN).
Old children are removed; the new node becomes the sole document element when the tree allows it.
📈 Practical Patterns
UI rebuilds on body, error handling, and comparison with append.
Example 3 — Everyday UI: body.replaceChildren()
Same method name on Element — the safe way to rebuild page content.
JavaScript
const title = document.createElement("h1");
title.textContent = "Hello again";
const note = document.createElement("p");
note.textContent = "Rebuilt with Element.replaceChildren";
// Prefer this over document.replaceChildren() on a live page
document.body.replaceChildren(title, note);
console.log(document.body.children.length); // 2
Teach the Document API, then ship Element calls for real interfaces. See also Element.replaceChildren().
Example 4 — HierarchyRequestError on invalid trees
Two root elements are not allowed under an HTML Document.
JavaScript
const doc = new Document();
const a = doc.createElement("html");
const b = doc.createElement("html");
try {
doc.replaceChildren(a, b); // invalid: two element children
} catch (err) {
console.log(err.name); // "HierarchyRequestError"
}
Document.replaceChildren() is Baseline Widely available (MDN: across browsers since October 2020). Logos use the shared browser-image-sprite.png sprite from this project.
✓ Baseline Widely available
Document.replaceChildren()
ParentNode replaceChildren on Document — empty or swap document children; use Element.replaceChildren for UI.
BaselineWidely available
Google Chrome86+
Yes
Microsoft Edge86+
Yes
Mozilla Firefox78+
Yes
Apple Safari14+
Yes
Opera72+
Yes
Internet ExplorerNo
No
replaceChildren()Widely available
Bottom line: Use document.replaceChildren() to empty or reset in-memory Documents. On loaded pages, prefer Element.replaceChildren() on body or a container.
Wrap Up
Conclusion
document.replaceChildren() replaces or empties the Document’s children in one ParentNode call. Learn MDN’s empty pattern on new Document(), respect hierarchy rules, and use Element.replaceChildren() for everyday UI rebuilds.
Use Element.replaceChildren() for UI panels and lists
Pass real Node objects when you already have them
Catch HierarchyRequestError when experimenting with roots
Verify with children.length / documentElement
❌ Don’t
Call no-arg document.replaceChildren() on the live page
Assume two root elements are allowed under HTML Documents
Confuse Document and Element targets
Forget that the return value is undefined
Use Document.replaceChildren for every UI clear — prefer Element
Summary
Key Takeaways
Knowledge Unlocked
Five things to remember about replaceChildren()
Baseline ParentNode reset for Document children.
5
Core concepts
📝01
Returns
undefined
MDN
🗑02
Empty
no args
MDN
🎯03
UI
use Element
tip
⚠️04
Errors
Hierarchy*
MDN
🛡05
Status
Baseline
2020
❓ Frequently Asked Questions
MDN: Document.replaceChildren() replaces the existing children of a Document with a specified new set of children. With no arguments, the Document is emptied of all child nodes.
No. MDN marks Document.replaceChildren() as Baseline Widely available (across browsers since October 2020). It is not Deprecated, Experimental, or Non-standard.
MDN: call document.replaceChildren() with no arguments. Then document.children is an empty HTMLCollection.
Zero or more Node objects or strings (MDN). Strings become Text nodes. Invalid trees throw HierarchyRequestError.
Usually no for everyday UI. Emptying or replacing the live document root is destructive. Prefer Element.replaceChildren() on body or a container, or use replaceChildren on a new Document() when building documents in memory.
Same ParentNode API. Document.replaceChildren() targets the Document node itself; Element.replaceChildren() targets an element such as a div or body — the common choice for UI updates.
Did you know?
MDN’s Document page for replaceChildren() focuses on the empty call — the same ParentNode method powers Element and DocumentFragment, which is why UI tutorials almost always show el.replaceChildren() instead of the Document form.
