.replaceWith()

.replaceWith( newContent ) Returns: jQuery

Description: Replace each element in the set of matched elements with the provided new content.

  • version added: 1.2.replaceWith( newContent )

    newContentThe content to insert. May be an HTML string, DOM element, or jQuery object.

  • version added: 1.4.replaceWith( function )

    functionA function that returns an HTML string to replace the set of matched elements with.

The .replaceWith() method allows us to remove content from the DOM and insert new content in its place with a single call. Consider this DOM structure:

<div class="container">
  <div class="inner first">Hello</div>
  <div class="inner second">And</div>
  <div class="inner third">Goodbye</div>
</div>

We can replace the second inner <div> with specified HTML:

$('.second').replaceWith('<h2>New heading</h2>');

This results in the structure:

<div class="container">
  <div class="inner first">Hello</div>
  <h2>New heading</h2>
  <div class="inner third">Goodbye</div>
</div>

We could equally target all inner <div> elements at once:

$('.inner').replaceWith('<h2>New heading</h2>');

This causes all of them to be replaced:

<div class="container">
  <h2>New heading</h2>
  <h2>New heading</h2>
  <h2>New heading</h2>
</div>

Or, we could select an element to use as the replacement:

$('.third').replaceWith($('.first'));

This results in the DOM structure:

<div class="container">
  <div class="inner second">And</div>
  <div class="inner first">Hello</div>
</div>

From this example, we can see that the selected element replaces the target by being moved from its old location, not by being cloned.

The .replaceWith() method, like most jQuery methods, returns the jQuery object so that other methods can be chained onto it. However, it must be noted that the original jQuery object is returned. This object refers to the element that has been removed from the DOM, not the new element that has replaced it.

In jQuery 1.4 replaceWith, before, and after will also work on disconnected DOM nodes. For example if you were to do:

$("
").replaceWith("

");

Then you would end up with a jQuery set that contains only a paragraph.

Examples:

Example: On click, replace the button with a div containing the same word.

<!DOCTYPE html>
<html>
<head>
  <style>
  button { display:block; margin:3px; color:red; width:200px; }
  div { color:red; border:2px solid blue; width:200px; 
        margin:3px; text-align:center; }
  </style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<button>First</button>
  <button>Second</button>

  <button>Third</button>
<script>

    $("button").click(function () {
      $(this).replaceWith("<div>" + $(this).text() + "</div>");
    });
</script>
</body>
</html>

Demo:

Example: Replace all the paragraphs with bold words.

<!DOCTYPE html>
<html>
<head>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<p>Hello</p>
  <p>cruel</p>

  <p>World</p>
<script>$("p").replaceWith("<b>Paragraph. </b>");</script>
</body>
</html>

Demo:

Example: Replace all the paragraphs with empty div elements.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { border:2px solid blue; margin:3px; }
  </style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<p>Hello</p>

  <p>cruel</p>
  <p>World</p>
<script>$("p").replaceWith(document.createElement("div"));</script>
</body>
</html>

Demo:

Example: On click, replace each paragraph with a jQuery div object that is already in the DOM. Notice it doesn't clone the object but rather moves it to replace the paragraph.

<!DOCTYPE html>
<html>
<head>
  <style>
  div { border:2px solid blue; color:red; margin:3px; }
  p { border:2px solid red; color:blue; margin:3px; cursor:pointer; }
  </style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<p>Hello</p>
  <p>cruel</p>
  <p>World</p>

  <div>Replaced!</div>
<script>
    $("p").click(function () {
      $(this).replaceWith($("div"));
    });

</script>
</body>
</html>

Demo: