JavaScript Element replaceChildren() Method

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

Definition

Element.replaceChildren() replaces all existing children with a new set of Node objects or strings (MDN). Call it with no arguments to empty the element. Returns undefined.

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

Syntax

Call el.replaceChildren. Start with this line.

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

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

Library declarations
JavaScript
el.replaceChildren(…)

Parameters

ParameterDescription
param1…paramNOptional. Node objects and/or strings; omit to empty

Return Value

Return ValueDescription
*Always undefined

JavaScript Examples

Example 1 — Empty a Container (MDN)

Call with no arguments to remove every child.

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

console.log(box.childNodes.length); // 0
Try It Yourself

How It Works

  1. Select the parent that has children.
  2. Call replaceChildren() with no args (MDN).
  3. All children are removed in one step.
  4. Check length. childNodes.length is 0.

Example 2 — Replace with Nodes & Text

Swap old children for a paragraph and a string.

JavaScript
const box = document.getElementById("box");
const p = document.createElement("p");
p.textContent = "Hello";

box.replaceChildren(p, "!");
console.log(box.textContent); // "Hello!"
Try It Yourself

How It Works

  1. Build new content (here a p plus a string).
  2. Call replaceChildren. Old kids are cleared first.
  3. String becomes a Text node (same idea as append).
  4. Read textContent to confirm the new tree.

Example 3 — Transfer Nodes (MDN Idea)

Move selected options into another list without a manual loop.

JavaScript
const from = document.getElementById("no");
const to = document.getElementById("yes");

const moving = from.querySelectorAll("option:checked");
const keep = to.querySelectorAll("option");

to.replaceChildren(...moving, ...keep);
// moved options now live under "yes"
Try It Yourself

How It Works

  1. Collect nodes to move and nodes already in the target.
  2. Spread both lists into replaceChildren (MDN party-food pattern).
  3. Nodes move — they leave the old parent automatically.
  4. No clone. The same option elements are reused.
Compatibility

Browser Support

Element.replaceChildren() is Baseline Widely available on MDN (across browsers since October 2020). Safe for modern DOM updates.

✓ Baseline Widely available

Element.replaceChildren()

Replace or empty all children in one call — widely supported.

Wide Baseline
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Android WebView Supported · Modern WebView
Full support
replaceChildren() Widely available

Bottom line: Use replaceChildren() to empty or swap kids. Prefer over looping remove() for full resets.

Frequently Asked Questions

It replaces the existing children of an element with a new set of Node objects or strings (MDN). If no arguments are passed, the element is emptied of all child nodes.
No. MDN marks Element.replaceChildren() as Baseline Widely available (across browsers since October 2020). It is not Deprecated, Experimental, or Non-standard.
Call replaceChildren() with no arguments: el.replaceChildren(). MDN describes this as a convenient way to remove all children.
Zero or more Node objects or strings. Strings are inserted as equivalent Text nodes, like append() and prepend() (MDN).
undefined. There is no return value (MDN).
append() adds after the last child. replaceChildren() removes all existing children first, then inserts the new set.

Next: replaceWith()

Learn how to replace an element with new nodes or text.

replaceWith() 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)

24 people found this page helpful

JavaScript Element removeAttributeNS() Method JavaScript Element replaceWith() Method