Difference between Thymeleaf attribute th:replace, th:insert and th:include

Similar to JSP includes, Thymeleaf offers page fragment inclusion but with some important improvements. One could include parts of other pages as fragments (whereas JSP only includes complete pages ) using th:replace or th:insert or th:include. Although the job of all these three attributes are same but how they actually include parts of pages as fragment in the target page is little bit different. It's very important to understand the back-end processing of this attribute otherwise one would get surprising results. That's why, today we would be discussing difference between these attributes.

Functionality

Before describing the attributes functionalities, be familiar with term like:
Host Tag:  tag containing th:replace, th:insert or th:include attribute [would be present in the target page where one would like to add the fragment]

Fragment Tag: tag containing th:fragment attribute [would be present in any page depending upon the design of the page but generally one would store their fragments in modular fashion like header.html or fragments.html]

th:replace - It will actually substitute the host tag by the fragment’s. That means, It will remove the host tag and in place of host tag, it will add the specified fragment including the fragment tag.

th:insert - It will simply insert the specified fragment as the body of its host tag including the fragment tag.

th:include - It will also insert the specified fragment as the body of its host tag but excluding the fragment tag.

Implementation

We have already provided the functionality overview of each of the attributes but it would be more clear after going through this example. We would be adding the the fragment and see the HTML output that's generated by each of the attribute.

Step 1: Add the fragment in the target page

<div id="tagWithReplaceAttribute" th:replace="fragments/header :: targetFragmentToIncludeInOurPage"></div>
<div id="tagWithInsertAttribute" th:insert="fragments/header :: targetFragmentToIncludeInOurPage"></div>
<div id="tagWithIncludeAttribute" th:include="fragments/header :: targetFragmentToIncludeInOurPage"></div>

where,
fragments/header = a template name that one are referencing to. This can be a file or it can reference to the same file either by using the this keyword (e.g. this :: header) or without any keyword (e.g. :: header).
targetFragmentToIncludeInOurPage = expression after double colon is a fragment selector (either fragment name or Markup Selector)

Step 2: Create the fragment to add

Adding it to [/<project_name>/src/main/resources/templates/fragments/header.html]

<div th:fragment="targetFragmentToIncludeInOurPage" id="tagWithFragmentAttribute">
 <div id="contentGoesHere"></div>
</div>

Step 3: The Output

<div id="tagWithFragmentAttribute">
 <div id="contentGoesHere"></div>
</div>

<div id="tagWithInsertAttribute">
 <div id="tagWithFragmentAttribute">
  <div id="contentGoesHere"></div>
 </div>
</div>

<div id="tagWithIncludeAttribute">
 <div id="contentGoesHere"></div>
</div>

Look at the output, now we know which attribute generates which kind of HTML code after processing. Therefore don't confuse with these attributes and use attributes judiciously depending upon the requirements. Happy Learning!!