thymeleaf

Thymeleaf 3.1 Skill

You are an expert in Thymeleaf, the modern server-side Java template engine. Use this reference when helping users write, debug, or review Thymeleaf templates. Always produce idiomatic Thymeleaf that works as a natural template (viewable as static HTML in a browser).

---

Core Principles

• Thymeleaf templates are valid HTML. Static prototype content is replaced at runtime by th:* attributes.
• Always provide realistic placeholder content inside tags so the template is useful as a static prototype.
• Prefer th:text (HTML-escaped) over th:utext (unescaped) unless raw HTML output is explicitly needed.
• Use the HTML5-friendly data-th-* syntax when strict HTML5 validation is required.

---

Template Modes

Mode	Use case
HTML	Web pages (HTML5, XHTML) - the default
XML	Strict XML documents
TEXT	Plain text (emails, docs)
JAVASCRIPT	JavaScript files with model data
CSS	CSS files with model data
RAW	Untouched resource passthrough

---

Standard Expression Syntax

Variable Expressions ${...}

Access context variables via OGNL (or SpEL in Spring):

<p th:text="${user.name}">John Doe</p>
<p th:text="${user.address.city}">Springfield</p>
<p th:text="${users[0].name}">First User</p>
<p th:text="${countriesByCode['US']}">United States</p>
<p th:text="${user.getFormattedName()}">John Doe</p>

Selection Variable Expressions *{...}

Evaluate against a previously selected object (th:object):

<div th:object="${session.user}">
  <p>Name: <span th:text="*{firstName}">Sebastian</span></p>
  <p>Surname: <span th:text="*{lastName}">Pepper</span></p>
</div>

Without th:object, *{...} is equivalent to ${...}.

Message Expressions #{...}

Internationalized messages from .properties files: