When working with Spring Boot and Thymeleaf, developers often need to inject dynamic text into an HTML template. However, a common issue occurs when a Thymeleaf attribute replaces the entire HTML element content, accidentally removing important HTML structures such as nested tags, icons, or formatting. Let us understand how Thymeleaf renders dynamic text in Spring Web applications while preserving the existing HTML structure.
1. Introduction
Thymeleaf is a modern server-side template engine widely used with Spring Boot applications. It enables developers to create dynamic web pages by binding backend data directly to HTML templates. Unlike traditional templating engines that generate HTML from scratch, Thymeleaf works with natural HTML templates, meaning the templates can still be opened and viewed directly in a browser without requiring server-side processing.
In a typical Spring Web application, Thymeleaf integrates with the Spring MVC model. Data is passed from a controller to the view layer using a Model object, and the template engine replaces placeholders with real values at runtime. This approach helps keep the presentation layer clean and separates business logic from the UI.
Thymeleaf provides several attributes that allow developers to insert or manipulate dynamic content within HTML documents. Some of the commonly used attributes include:
th:text– replaces the text content of an HTML element with a variable value.th:utext– renders unescaped text, allowing HTML markup to be interpreted instead of displayed as plain text.th:inline– enables inline expressions inside HTML or JavaScript blocks.
These attributes make it easy to build dynamic pages, conditionally render content, and integrate data from backend services. However, developers must understand how these attributes behave when applied to HTML elements.
While these attributes are powerful, using them incorrectly may overwrite the entire content of an HTML tag.
1.1 The Common Mistake: Breaking HTML Structure
A common mistake occurs when developers apply the th:text attribute directly to an HTML element that already contains other nested elements. Because th:text replaces the entire body of the element, any child tags inside that element are removed during template rendering.
For example, consider the following HTML structure:
<h2 th:text="${message}">
<i>★</i>
Default Message
</h2>
In this case, Thymeleaf replaces everything inside the <h2> element with the value of ${message}. As a result, the icon element <i> is removed from the final rendered page. This behavior is expected because th:text replaces the entire inner content of the element rather than updating only the text portion. To avoid breaking the HTML structure, it is recommended to place the dynamic content inside a child element such as <span>.
2. Code Example
The following example demonstrates how to render dynamic text in Thymeleaf while preserving the existing HTML structure.
2.1 Maven pom.xml
The following Maven configuration defines the required dependencies for running a Spring Boot application with Thymeleaf template support.
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>thymeleaf-demo</artifactId>
<version>1.0</version>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.2.0</version>
</parent>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
</dependencies>
</project>
This pom.xml file defines the project dependencies. The spring-boot-starter-web dependency provides web functionality such as embedded Tomcat and MVC support. The spring-boot-starter-thymeleaf dependency enables Thymeleaf template rendering in Spring Boot applications.
2.2 Spring Boot Main Class
The following class represents the main entry point of the Spring Boot application and is responsible for starting the application.
package com.example.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
This is the entry point of the Spring Boot application. The @SpringBootApplication annotation enables auto-configuration, component scanning, and configuration support. When the application starts, SpringApplication.run() initializes the Spring context and launches the embedded server.
2.3 Controller
The following controller processes incoming web requests and passes dynamic data to the Thymeleaf template.
package com.example.demo;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
@Controller
public class HomeController {
@GetMapping("/")
public String home(Model model) {
model.addAttribute("message",
"Welcome to Thymeleaf Dynamic Rendering");
return "home";
}
}
This controller handles HTTP requests sent to the root URL (/). The @Controller annotation marks the class as a Spring MVC controller. The method adds a variable named message to the model object. This variable is then accessible in the Thymeleaf template. The method returns home, which tells Spring Boot to render the home.html template.
2.4 Thymeleaf Template (home.html)
The following Thymeleaf template demonstrates how dynamic data from the controller is rendered inside an HTML page.
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>Thymeleaf Example</title>
</head>
<body>
<h2>
<i>★</i>
<span th:text="${message}">Default Message</span>
</h2>
</body>
</html>
This is the Thymeleaf template responsible for rendering the view. The namespace xmlns:th enables Thymeleaf attributes in the HTML document. Inside the <h2> tag, an icon element <i> is used. The dynamic text is inserted inside a child <span> using the attribute th:text="${message}". Using a child element ensures that the existing HTML structure remains intact. If th:text were applied directly to the <h2> element, the icon would be removed because Thymeleaf replaces the entire content of that element. This is a common mistake when working with Thymeleaf templates because developers often expect the attribute to update only the text, while in reality, it replaces the entire element content.
2.5 Application Output
Run the Spring Boot application and open the browser:
http://localhost:8080
This URL triggers the controller method, which sends the message variable to the template.
The icon remains visible because only the text inside the <span> element is replaced. This approach preserves the original HTML layout while still allowing dynamic data to be rendered.
3. Conclusion
Rendering dynamic text in Thymeleaf is straightforward, but developers must be careful when using attributes like th:text on parent elements. The key points to remember are that th:text replaces the entire element body, th:inline="text" allows inline variable rendering without replacing the surrounding HTML structure, and using a child element such as <span> is usually the safest and cleanest approach. By following these practices, developers can safely inject dynamic text while preserving the integrity of the HTML layout, ensuring that Thymeleaf templates remain maintainable, predictable, and visually consistent.
