.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 content with which to replace the set of matched elements.
The .replaceWith() method removes content from the DOM and inserts 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>
The second inner <div> could be replaced with the specified HTML:
$('div.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>
All inner <div> elements could be targeted at once:
$('div.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>
An element could also be selected as the replacement:
$('div.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>
This example demonstrates 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.
As of jQuery 1.4, .replaceWith() can also work on disconnected DOM nodes. For example, with the following code, .replaceWith() returns a jQuery set containing only a paragraph.:
$("<div/>").replaceWith("<p></p>");
The .replaceWith() method can also take a function as its argument:
$('div.container').replaceWith(function() {
return $(this).contents();
});
This results in <div class="container"> being replaced by its three child <div>s. The return value of the function may be an HTML string, DOM element, or jQuery object.
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-1.7rc2.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>Example: Replace all paragraphs with bold words.
<!DOCTYPE html>
<html>
<head>
<script src="http://code.jquery.com/jquery-1.7rc2.js"></script>
</head>
<body>
<p>Hello</p>
<p>cruel</p>
<p>World</p>
<script>
$("p").replaceWith( "<b>Paragraph. </b>" );
</script>
</body>
</html>Example: On click, replace each paragraph with a div that is already in the DOM and selected with the $() function. 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-1.7rc2.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>Example: On button click, replace the containing div with its child divs and append the class name of the selected element to the paragraph.
<!DOCTYPE html>
<html>
<head>
<style>
.container { background-color: #991; }
.inner { color: #911; }
</style>
<script src="http://code.jquery.com/jquery-1.7rc2.js"></script>
</head>
<body>
<p>
<button>Replace!</button>
</p>
<div class="container">
<div class="inner">Scooby</div>
<div class="inner">Dooby</div>
<div class="inner">Doo</div>
</div>
<script>
$('button').bind("click", function() {
var $container = $("div.container").replaceWith(function() {
return $(this).contents();
});
$("p").append( $container.attr("class") );
});
</script>
</body>
</html>