A 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:

1

2

3

4

5

<divclass="container">

<divclass="inner first">Hello</div>

<divclass="inner second">And</div>

<divclass="inner third">Goodbye</div>

</div>

The second inner <div> could be replaced with the specified HTML:

1

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

This results in the structure:

1

2

3

4

5

<divclass="container">

<divclass="inner first">Hello</div>

<h2>New heading</h2>

<divclass="inner third">Goodbye</div>

</div>

All inner <div> elements could be targeted at once:

1

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

This causes all of them to be replaced:

1

2

3

4

5

<divclass="container">

<h2>New heading</h2>

<h2>New heading</h2>

<h2>New heading</h2>

</div>

An element could also be selected as the replacement:

1

$( "div.third" ).replaceWith( $( ".first" ) );

This results in the DOM structure:

1

2

3

4

<divclass="container">

<divclass="inner second">And</div>

<divclass="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.

Additional Notes:

The .replaceWith() method removes all data and event handlers associated with the removed nodes.

Prior to jQuery 1.9, .replaceWith() would attempt to add or change nodes in the current jQuery set if the first node in the set was not connected to a document, and in those cases return a new jQuery set rather than the original set. The method might or might not have returned a new result depending on the number or connectedness of its arguments! As of jQuery 1.9, .after(), .before(), and .replaceWith() always return the original unmodified set. Attempting to use these methods on a node without a parent has no effect—that is, neither the set nor the nodes it contains are changed.

Examples:

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

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

<!doctype html>

<htmllang="en">

<head>

<metacharset="utf-8">

<title>replaceWith demo</title>

<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>

<scriptsrc="https://code.jquery.com/jquery-1.10.2.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 paragraphs with bold words.

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

<!doctype html>

<htmllang="en">

<head>

<metacharset="utf-8">

<title>replaceWith demo</title>

<scriptsrc="https://code.jquery.com/jquery-1.10.2.js"></script>

</head>

<body>

<p>Hello</p>

<p>cruel</p>

<p>World</p>

<script>

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

</script>

</body>

</html>

Demo:

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.

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

<!doctype html>

<htmllang="en">

<head>

<metacharset="utf-8">

<title>replaceWith demo</title>

<style>

div{

border:2px solid blue;

color: red;

margin:3px;

}

p{

border:2px solid red;

color: blue;

margin:3px;

cursor: pointer;

}

</style>

<scriptsrc="https://code.jquery.com/jquery-1.10.2.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:

Example: On button click, replace the containing div with its child divs and append the class name of the selected element to the paragraph.