JavaScript Document replaceChildren() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method
Decorative image with the word REPLACECHILDREN

Definition

document.replaceChildren(...nodesOrStrings) replaces the existing children of a Document with a new set. With no arguments, it empties the document. Strings become Text nodes. Returns undefined.

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call document.replaceChildren. Start with this line.

JavaScript
document.replaceChildren(…nodesOrStrings)
CallWhat it does
document.replaceChildren(…nodesOrStrings)Primary signature.
document.replaceChildren(...)Call with the arguments your case needs.

Built into the browser. Call replaceChildren(...) on document — no import required.

Library declarations
JavaScript
document.replaceChildren(…nodesOrStrings)

Parameters

ParameterDescription
param1…paramNOptional. New children; omit to empty

Return Value

Return ValueDescription
*Always undefined

JavaScript Examples

Example 1 — Empty a Document (MDN)

Call with no arguments to remove every Document child.

JavaScript
const doc = new Document();
const html = doc.createElement("html");
doc.append(html);

doc.replaceChildren();

console.log(doc.children.length);  // 0
Try It Yourself

How It Works

  1. Build a tiny document. Append a root so there is something to clear.
  2. Call with no args. MDN: the Document is emptied of all child nodes.
  3. Check children.length. It becomes 0.
  4. Do not try this on the live tutorial page unless you intend to wipe it.

Example 2 — Replace Children with a Root

Swap whatever was there for a single <html> element.

JavaScript
const doc = new Document();
const oldRoot = doc.createElement("html");
doc.append(oldRoot);

const html = doc.createElement("html");
doc.replaceChildren(html);

console.log(doc.children.length);           // 1
console.log(doc.documentElement === html);  // true
Try It Yourself

How It Works

  1. Start with a root. The old html is the current child.
  2. Create a new root. Use the same document’s createElement.
  3. Replace in one call. Old children are removed; the new root is attached.
  4. Verify. documentElement matches the new node.

Example 3 — Everyday UI with body.replaceChildren()

Same ParentNode API on an element — the usual way to rebuild page content.

JavaScript
const box = document.createElement("div");
box.append(document.createElement("span"), " old");

const note = document.createElement("p");
note.textContent = "Hello";

box.replaceChildren(note, " from replaceChildren");

console.log(box.childNodes.length);  // 2
console.log(box.firstChild.tagName); // "P"
Try It Yourself

How It Works

  1. Use a container. A div stands in for body or a panel.
  2. Replace its children. Old nodes are removed in one step.
  3. Pass a node and a string. The string becomes a Text node.
  4. Why this path. On live pages, Element replaceChildren is the safe everyday API.
Compatibility

Browser Support

Document.replaceChildren() is a browser DOM API marked Baseline Widely available on MDN (across browsers since October 2020).

✓ Baseline Widely available

Document.replaceChildren()

ParentNode replaceChildren on Document — empty or rebuild Document children; use element.replaceChildren for UI.

Baseline Widely available
Google Chrome 86+
Yes
Microsoft Edge 86+
Yes
Mozilla Firefox 78+
Yes
Apple Safari 14+
Yes
Opera 72+
Yes
Internet Explorer No
No
replaceChildren() Excellent in browsers

Bottom line: Safe in modern browsers. On a loaded page prefer element/body.replaceChildren(). See the MDN Document.replaceChildren() reference.

Frequently Asked Questions

It replaces the existing children of a Document with a new set of Nodes or strings. 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.
Call document.replaceChildren() with no arguments. Then document.children is an empty HTMLCollection.
Zero or more Node objects or strings. 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.

Next: requestStorageAccess()

Learn how documents request access to unpartitioned storage / cookies.

requestStorageAccess() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

15 people found this page helpful

JavaScript Document releaseCapture() Method JavaScript Document requestStorageAccess() Method