JavaScript Element replaceWith() Method

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

Definition

Element.replaceWith() replaces this element in its parent’s children list with one or more Node objects or strings (MDN). 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 el.replaceWith. Start with this line.

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

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

Library declarations
JavaScript
el.replaceWith(…)

Parameters

ParameterDescription
param1…paramNRequired. Node objects and/or strings

Return Value

Return ValueDescription
*Always undefined

JavaScript Examples

Example 1 — Replace with an Element (MDN)

Swap a p for a span inside the same parent.

JavaScript
const div = document.createElement("div");
const p = document.createElement("p");
div.appendChild(p);

const span = document.createElement("span");
p.replaceWith(span);

console.log(div.outerHTML);
// "<div><span></span></div>"
Try It Yourself

How It Works

  1. Build a parent that contains p.
  2. Create the replacement (span).
  3. Call p.replaceWith(span). p leaves; span takes its place (MDN).
  4. Inspect the parent. outerHTML shows the new child.

Example 2 — Replace with a String

Strings become Text nodes in the same spot.

JavaScript
const item = document.getElementById("item");
item.replaceWith("done");

console.log(item.parentNode); // null
console.log(document.body.textContent);
Try It Yourself

How It Works

  1. Select the element to replace.
  2. Pass a string. The browser inserts a Text node (MDN).
  3. Old element is detached — parentNode is null.
  4. Text remains where the element used to be.

Example 3 — Multiple Replacements

One call can insert several nodes in place of the old element.

JavaScript
const old = document.getElementById("old");
const a = document.createElement("em");
a.textContent = "A";
const b = document.createElement("strong");
b.textContent = "B";

old.replaceWith(a, " · ", b);
// parent now has: em, text, strong
Try It Yourself

How It Works

  1. Prepare several nodes/strings to insert.
  2. Call replaceWith with all of them (MDN).
  3. Old element is gone; the args appear in order.
  4. One call replaces “one node → many” without extra inserts.
Compatibility

Browser Support

Element.replaceWith() is Baseline Widely available on MDN (across browsers since April 2018). Safe for everyday DOM swaps.

✓ Baseline Widely available

Element.replaceWith()

Replace this element with nodes or text — 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
replaceWith() Widely available

Bottom line: Call el.replaceWith(…) to swap the element itself. Use replaceChildren() when you only need to change its kids.

Frequently Asked Questions

It replaces this element in its parent's children list with the specified Node objects or strings (MDN). Strings become Text nodes.
No. MDN marks Element.replaceWith() as Baseline Widely available (across browsers since April 2018). It is not Deprecated, Experimental, or Non-standard.
undefined. There is no return value (MDN). The original element is removed from the DOM.
replaceWith() replaces the element itself. replaceChildren() replaces only the children inside an element.
Yes. replaceWith(node1, node2, …) inserts all arguments in place of the element you call it on (MDN).
Yes. MDN: replaceWith() is not available inside a with statement — use el.replaceWith(...) instead.

Next: requestFullscreen()

Learn how to display an element in fullscreen mode.

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

20 people found this page helpful

JavaScript Element replaceChildren() Method JavaScript Element requestFullscreen() Method