jQuery .replaceWith() Method

What You’ll Learn

The .replaceWith() method removes matched elements and inserts new content in one step — target first, replacement second. This tutorial covers HTML string replacements, moving existing DOM nodes, the callback form since jQuery 1.4, comparisons with .replaceAll() and .html(), what the return value refers to, and five practical try-it examples from the official jQuery API.

Introduction

When you already know which elements to remove — every <p>, a clicked button, or a stale widget container — .replaceWith() is the natural choice. You select the old nodes, pass the new content, and jQuery swaps them in a single call.

Available since jQuery 1.2, .replaceWith( newContent ) accepts an HTML string, DOM element, array of elements, or jQuery object as replacement. Since jQuery 1.4, pass a callback function that returns the new content for each matched element individually.

Pair with .replaceAll() when replacement content is selected first. Browse the jQuery DOM hub for related manipulation methods.

Understanding the .replaceWith() Method

.replaceWith( newContent ) operates on the jQuery collection you want to remove. Each matched element is deleted from the DOM and newContent is inserted in its place. The method returns the original jQuery object — the removed elements — not the replacement.

Replaced nodes lose all jQuery data and event handlers. When newContent is an existing DOM node already on the page, jQuery moves it into position rather than cloning it (for single-target swaps).

📝 Syntax

jQuery .replaceWith() supports two forms:

Replace with content — since 1.2

.replaceWith( newContent )

• newContent — HTML string, DOM element, array of elements, or jQuery object.
• Returns — the original jQuery collection of removed elements.

Replace with callback — since 1.4

.replaceWith( function )

$( "button" ).replaceWith( function() {
  return $( "<div>" + $( this ).text() + "</div>" );
} );

Official replaceWith pattern

$( "p" ).replaceWith( "<b>Paragraph.</b>" );

Examples Gallery

Examples 1–2 follow the official jQuery API documentation. Examples 3–5 cover moving existing nodes, callback replacements, and unwrapping a container. Use DevTools or the Try-it links to run each snippet in the browser.

$( "p" ).replaceWith( "<b>Paragraph.</b>" );

// Equivalent content-first form:
// $( "<b>Paragraph.</b>" ).replaceAll( "p" );

Before: <p>Hello</p> <p>cruel</p> <p>World</p>
After:  <b>Paragraph.</b> (×3)
Removed <p> nodes lose data/events

Official jQuery API Example 2 pattern

$( "button" ).on( "click", function() {
  $( this ).replaceWith( "<div>" + $( this ).text() + "</div>" );
} );

Click "First": <button> → <div>First</div>
Button removed; cannot be clicked again
Each button replaced independently on click

Official jQuery API Example 1 pattern

$( "p" ).on( "click", function() {
  $( this ).replaceWith( $( "div" ) );
} );

// The lone <div>Replaced!</div> moves into the clicked paragraph's slot
// Only one div exists — moved, not duplicated

Click any <p>: that paragraph removed
The existing <div> moves into its place
Original div location becomes empty

Official jQuery API Example 3 pattern

$( "button" ).replaceWith( function() {
  return $( "<div class='replaced'>" + $( this ).text() + "</div>" );
} );

Each button → <div class="replaced"> with same label
Callback runs once per matched button
this inside callback = DOM element being replaced

var $removed = $( "div.container" ).replaceWith( function() {
  return $( this ).contents();
} );

// Container gone; inner .inner divs remain in DOM
// $removed holds the removed container — read .attr("class") if needed

Before: <div class="container"><div class="inner">…</div>…</div>
After:  <div class="inner">Scooby</div> <div class="inner">Dooby</div> …
$removed.attr("class") → "container"

Official jQuery API Example 4 pattern

🚀 Common Use Cases

• Upgrade markup — replace deprecated elements with semantic HTML5 tags.
• Click-to-transform — replace a button with a status div after submission.
• Move widgets — swap a placeholder with an existing DOM component.
• Unwrap containers — remove wrapper divs while keeping children via callback.
• Batch replacement — replace all matching nodes with standardized HTML.
• Dynamic templates — callback builds unique replacement per element.

📝 Notes

• Available since jQuery 1.2; callback form since jQuery 1.4.
• Returns the removed jQuery collection — not the inserted replacement.
• Since jQuery 1.9, always returns the original unmodified set consistently.
• Removed nodes lose jQuery data and event handlers.
• Existing DOM nodes used as replacement are moved, not cloned (single-target case).
• Replacing a node not connected to a document has no effect since jQuery 1.9.
• Pair with .replaceAll() when content-first syntax reads more clearly.

💡 Best Practices