.replaceWith()

jQuery

previous page next page

.replaceWith()

Categories: Manipulation > DOM Replacement

.replaceWith( newContent ) Returns: jQuery

Description: Replace each element in the set of matched elements with the provided new content and return the set of elements that was removed.

  • version added: 1.2.replaceWith( newContent )

    • newContent
      Type: htmlString or Element or jQuery
      The content to insert. May be an HTML string, DOM element, or jQuery object.

  • version added: 1.4.replaceWith( function )

    • function
      Type: Function()
      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
 
                                

                                  

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

1
 
                                

                                  

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

This results in the structure:

1
2
3
4
5
 
                                

                                  

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

1
 
                                

                                  

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

This causes all of them to be replaced:

1
2
3
4
5
 
                                

                                  

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

1
 
                                

                                  

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

This results in the DOM structure:

1
2
3
4
 
                                

                                  

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

1
 
                                

                                  

                                    $("<div/>").replaceWith("<p></p>");

The .replaceWith() method can also take a function as its argument:

1
2
3
 
                                

                                  

                                    $('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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
                                  

                                    

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

Example: Replace all paragraphs with bold words.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
                                  

                                    

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

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
 
                                  

                                    

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

Example: On button click, replace the containing div with its child divs and append the class name of the selected element to 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
 
                                  

                                    

                                      
                                        <!DOCTYPE html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <head>
                                      
                                    

                                  

                                  

                                    

                                        <style>
                                    

                                  

                                  

                                    

                                        .container { background-color: #991; }
                                    

                                  

                                  

                                    

                                        .inner { color: #911; }
                                    

                                  

                                  

                                    

                                        </style>
                                    

                                  

                                  

                                    

                                        <script src="http://code.jquery.com/jquery-latest.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').on("click", function() {
                                    

                                  

                                  

                                    

                                        var $container = $("div.container").replaceWith(function() {
                                    

                                  

                                  

                                    

                                          return $(this).contents();
                                    

                                  

                                  

                                    

                                        });
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                        $("p").append( $container.attr("class") );
                                    

                                  

                                  

                                    

                                      });
                                    

                                  

                                  

                                    

                                      
                                        </script>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        </body>
                                      
                                    

                                  

                                  

                                    

                                      
                                        </html>
 POWERED BYHERONOTE
previous page start next page