replaceWith()?.replaceWith(newContent) replaces each matched element with new content (since jQuery 1.2). Target comes first; content is the argument — the reverse of .replaceAll(). A function form was added in 1.4.
$("p").replaceWith("<b>Paragraph.</b>")
$("div.second").replaceWith("<h2>New heading</h2>")
$("div.third").replaceWith($(".first")) // move existing node
// same DOM result, reversed syntax:
$("<b>Paragraph.</b>").replaceAll("p")
// returns the removed set — not the new nodes
var $gone = $("#status").replaceWith("<strong>Done</strong>");| Need | Use |
|---|---|
| Target first, swap out | $(target).replaceWith(content) |
| Content first | $(content).replaceAll(target) |
| Change inside only | .html() |
| Delete without replacement | .remove() |
replaceWith()Select what to remove, pass the replacement, swap them out.
.replaceWith(newContent) — each match is swapped.| Piece | Required? | Role |
|---|---|---|
| jQuery collection | Yes | Elements to replace (targets) |
newContent | Yes* | HTML, element(s), or jQuery |
function | Alt* | Per-element replacement (1.4+) |
| Return | — | Original removed set |
* Pass either newContent or a function, not both.
targets = matched elements
content = newContent // or content = fn.call(each target)
for each t in targets:
remove t (and its data/events)
if first target:
put content in t's place // move if already in DOM
else:
clone content into t's place
return original targets // removed set, not the new nodes
// Same idea as .replaceAll(), reversed syntax:
// target.replaceWith(content) ≡ content.replaceAll(target)Keep these facts handy while swapping elements.
| Topic | Detail |
|---|---|
| Syntax | .replaceWith(newContent) or .replaceWith(fn) |
| Since | 1.2 (content) · 1.4 (function) |
vs .replaceAll() | Target-first vs content-first |
| Return | Removed set (not replacements) |
| One match | Existing nodes move |
| Many matches | Clones after the first |
| Cleanup | Data and events on removed nodes |
vs .html() | Whole element vs inner content |
Run official-style replaceWith actions on a tiny demo tree and see matched elements swap for new content.
Short, copy-ready snippets. Open DevTools Console, or use Try It Yourself for a live editor.
Swap every <p> for a bold “Paragraph.” element.
// <p>Hello</p><p>cruel</p><p>World</p>
$("p").replaceWith("<b>Paragraph.</b>");p is in the matched set..secondReplace one middle .inner div with a new heading.
// <div class="container">
// <div class="inner first">Hello</div>
// <div class="inner second">And</div>
// <div class="inner third">Goodbye</div>
// </div>
$("div.second").replaceWith("<h2>New heading</h2>");div.second matches.h2..first and .third are untouched.Use one existing element as the replacement — it moves, not clones.
// Start: .first Hello, .second And, .third Goodbye
$("div.third").replaceWith($(".first"));
// Result: And, then Hello (moved) — .third is gonediv.third will be removed.$(".first") is an existing DOM node.replaceWith vs replaceAllSame swap; pick target-first or content-first syntax.
// Target first
$("#status").replaceWith("<strong>Done</strong>");
// Content first — same DOM result
$("<strong>Done</strong>").replaceAll("#status");replaceWith reads well when the old node is selected.replaceAll reads well when the new node is ready.#status is removed; <strong> takes its place.replaceWith gives you the removed set.contents()Replace a container with its own children using the function form (1.4+).
// <div class="container">
// <div class="inner">Scooby</div>
// <div class="inner">Dooby</div>
// <div class="inner">Doo</div>
// </div>
$("div.container").replaceWith(function () {
return $(this).contents();
});
// Children stay; the outer .container is gonethis. Inside, this is the DOM element being replaced..contents() is what replaces the container.Check these before swapping nodes in real pages.
Do not expect the new nodes from the return value. Keep a separate reference if you need the replacements.
Handlers on matched elements are cleared. Tear down carefully if you need custom cleanup first.
On nodes without a parent, .replaceWith() does nothing and still returns the original set.
To change only contents, use .html().
Prefer .text() for user strings when building replacement nodes.
.replaceWith() is a core jQuery method (since 1.2; function form 1.4). It needs a browser DOM with jQuery loaded.
Works in Chrome, Firefox, Safari, Edge, and other browsers with jQuery. Not for Node.js without a DOM.
Bottom line: Use .replaceWith(newContent) in the browser for target-first element swaps. Prefer .replaceAll() when you build the replacement first.
| Approach | Cost | Best for |
|---|---|---|
.replaceWith(one) | Low | Single element swap / move |
.replaceWith(many) | Higher | Clones per extra match |
.html() | Often lower | Updating inside a kept shell |
Prefer one clear replace over many tiny swaps in a loop. If you only need new inner content, .html() is usually cheaper.
.replaceAll().One line: $(target).replaceWith(content) swaps matched elements for content — target-first twin of .replaceAll().
Check whether an element still has any jQuery data stored on it.
9 people found this page helpful