jQuery .replaceAll() Method

What You’ll Learn

The .replaceAll() method replaces target elements with the matched set — content first, target second. This tutorial covers the official jQuery demo, new HTML replacements, moving existing nodes, comparisons with .replaceWith() and .html(), data/event cleanup on removed targets, move vs clone behavior, and five practical try-it examples.

Introduction

Sometimes you need to swap one DOM element for another — upgrade plain paragraphs to styled headings, replace deprecated markup with accessible components, or move an existing node into a new position by replacing a placeholder. jQuery’s .replaceAll() handles that in one call.

Available since jQuery 1.2, .replaceAll( target ) is the content-first counterpart to .replaceWith(). You build or select the replacement elements first, then pass a selector or jQuery object identifying what to remove. Each target node is removed from the DOM and the replacement takes its place.

Important: replaced target nodes lose their jQuery data and event handlers. When a single replacement moves into one slot, jQuery moves the node rather than cloning it. Browse the jQuery DOM hub and .insertBefore() for related content-first APIs.

Understanding the .replaceAll() Method

.replaceAll( target ) operates on the jQuery collection that becomes the new content. The target argument identifies elements to remove — a selector string, DOM element, array of elements, or jQuery object. The method returns the replacement collection for chaining.

Think of it as reversed .replaceWith(): $( "p" ).replaceWith( "<b>Hi</b>" ) starts from the paragraphs; $( "<b>Hi</b>" ).replaceAll( "p" ) starts from the new content. Both produce the same final DOM when used correctly.

📝 Syntax

jQuery .replaceAll() has one form:

Replace targets with matched elements — since 1.2

.replaceAll( target )

• target — selector, DOM element, array of elements, or jQuery object to replace.
• Returns — the replacement jQuery collection.
• Removed targets lose associated data and event handlers.

Official replaceAll pattern

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

Reversed replaceWith equivalent

// These produce the same result:
$( "p" ).replaceWith( "<b>Paragraph.</b>" );
$( "<b>Paragraph.</b>" ).replaceAll( "p" );

Examples Gallery

Example 1 follows the official jQuery API documentation. Examples 2–5 cover replacing with new HTML, moving an existing node, swapping by class, and upgrading deprecated buttons. Use DevTools or the Try-it links to run each snippet in the browser.

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

// Before: <p>Hello</p> <p>cruel</p> <p>World</p>
// After:  <b>Paragraph.</b> (×3 — one per replaced p)

Before: three <p> elements with original text
After: three <b>Paragraph.</b> elements
Original <p> nodes removed — data/events on them cleared

Official jQuery API demo pattern

$( "<h2>New heading</h2>" ).replaceAll( ".inner" );

// DOM before:
// <div><span class="inner">Hello</span></div>
// <div><span class="inner">And</span></div>
// <div><span class="inner">Goodbye</span></div>

// DOM after: three <h2>New heading</h2> elements

Three .inner spans → three h2 "New heading" elements
Parent divs remain; only the span nodes are swapped
jQuery API documentation inner-span example

$( ".first" ).replaceAll( ".third" );

// Before: ... Hello (first) ... Goodbye (third)
// After:  ... Goodbye slot now contains Hello
// The .first element is MOVED — not duplicated

.first element disappears from original parent
.third element removed; .first now occupies that spot
Single replacement → move, not clone (jQuery API note)

// HTML: #real-content hidden in sidebar, .placeholder in main area

$( "#real-content" ).replaceAll( ".placeholder" );

// Placeholder removed; real content now in main area
// #real-content moved from sidebar — one node, one target

Sidebar #real-content moves into main .placeholder slot
Placeholder span removed from DOM
Useful for progressive enhancement / lazy layout swaps

$( ".btn-old" ).each(function() {
  var label = $( this ).text();
  $( "<button type='button' class='btn-new'></button>" )
    .text( label )
    .replaceAll( this );
} );

// Each .btn-old replaced by a proper <button> with same label
// Old nodes and their handlers are removed

Submit → <button class="btn-new">Submit</button>
Cancel  → <button class="btn-new">Cancel</button>
Each .btn-old div replaced; re-bind .on("click") on new buttons if needed

🚀 Common Use Cases

• Markup upgrades — swap deprecated tags for semantic HTML5 elements.
• Template promotion — move hidden template content into visible slots.
• Batch replacement — replace every matching node with standardized content.
• DOM restructuring — move an existing widget to replace a placeholder.
• Content migration — replace legacy class-based components with new ones.
• Progressive enhancement — replace noscript fallbacks with interactive UI.

📝 Notes

• Available since jQuery 1.2.
• Content-first syntax — reversed from .replaceWith().
• Removed target nodes lose jQuery data and event handlers.
• Single replacement into single target: element is moved, not cloned.
• Multiple targets may clone the replacement after the first insertion.
• Re-bind events on new elements after replacement if the old targets had handlers.
• Not the same as JavaScript String.prototype.replaceAll() for text strings.

💡 Best Practices