Thymeleaf

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the section bibliography.

This section is written against Thymeleaf 3.1.5 (released 2026-04-21), the version managed by Spring Boot 4.1.1 together with Spring Framework 7.0.9, Thymeleaf Layout Dialect 4.0.1 and htmx-spring-boot 5.2.0 (versions verified on 2026-10-07). Thymeleaf 3.1.5 is the minimum version this section teaches, because 3.1.4 and 3.1.5 together fixed the three 2026 expression-sandbox advisories. Thymeleaf has no formal end-of-life policy: in practice only the 3.1 line receives fixes, the 3.0 and 2.x lines are unsupported, and the project’s open milestones are 3.1.6, 3.2.0 and 4.0, none of them with a date. The Spring integration module is still called thymeleaf-spring6 (there is no thymeleaf-spring7), and it works with Spring Framework 7. Where the books or older tutorials describe different behaviour, the pages say so, and What’s Changed & Migration collects every difference in one place.

What Thymeleaf is

Thymeleaf is a server-side Java template engine for web and standalone environments. Its defining idea is the natural template: a template is a valid HTML file that a browser can open directly as a static prototype, and that Thymeleaf turns into a dynamic page by evaluating attributes such as th:text and th:each on the server. Because the dynamic logic lives in attributes the browser ignores, designers and developers can work on the same files.

A single engine provides:

  • six template modes (HTML, XML, TEXT, JAVASCRIPT, CSS and RAW), template resolvers, a context, and parsed-template and expression caches

  • the Standard Dialect and its Spring flavour, the SpringStandard Dialect, built from attribute, element and model processors, with the Standard Expression language (${...}, *{...}, #{...}, @{...}, ~{...}) and a family of utility objects

  • fragments and, through the community Layout Dialect, layout inheritance

  • inlining for text, JavaScript and CSS, and the textual template modes for emails and generated files

  • integration with Spring MVC and Spring WebFlux, Spring Security (sec:* attributes), Spring’s conversion, validation and message infrastructure

  • an extension model for your own dialects and processors

This section is for developers who:

  • know Java and want to build server-rendered web applications on Spring Boot, with forms, validation, security, internationalization and a maintainable layout system

  • want interactive pages without a single-page application, using fragment rendering, htmx and Alpine.js

  • learned Thymeleaf from older books and tutorials (Spring Boot 2, Thymeleaf 3.0, htmx 1) and need the current idioms

  • are choosing between Thymeleaf and Vaadin, JSF or the template engines of other stacks, and want the trade-offs

The Bookshelf scenario

Every example builds one small original application, Bookshelf, in the same domain as the Django, PHP and Laravel and Next.js sections, so that the stacks can be compared page by page. Here it is a Spring Boot 4.1 and Thymeleaf application, the first Java implementation of the scenario:

  • a public catalogue of books, authors and reviews with pagination, sorting and search

  • a shared layout with header, navigation, flash messages and footer, and reusable fragment components

  • create, edit and delete forms with Bean Validation, conversion, cover-image upload and dynamic rows

  • English and Spanish internationalization with a locale switcher

  • sign-in with Spring Security (form login, the roles READER and LIBRARIAN), sec:* attributes and CSRF

  • an htmx-enhanced version: active search, click to load, inline editing, delete with confirmation, out-of-band counters, inline validation and Server-Sent Events notifications

  • loan-reminder emails rendered from HTML and text templates

  • an optional WebFlux variant of the catalogue

  • tests with @WebMvcTest, HtmlUnit and end-to-end tools, Tailwind CSS v4 styling and a container deployment

Diagram of the Bookshelf application. The browser sends full page requests, form posts and htmx partial requests through the Spring Security filters (form login, CSRF token, roles) to a Spring MVC controller, which binds and validates input and calls a service. The service uses a Spring Data JPA repository that reads and writes the database. The controller fills the model and returns a view name, or a fragment name for htmx, to the Thymeleaf view layer, which renders the templates and returns the HTML response to the browser. Static resources such as CSS, htmx, Alpine.js and images are served separately.
Figure 1. The Bookshelf application: browser, security filters, Spring MVC controller, service, repository, database, Thymeleaf view layer and static resources

The final project layout (src/main/java packages for book, author, review, security and web, and src/main/resources/templates folders for layout, fragments, books, authors, reviews, error and mail) is assembled on Getting Started.

Reading path

The pages are ordered so that each one builds on the previous ones. Read them in this order the first time, then use them as a reference. Before starting, be comfortable with the language and the framework underneath: the Java Reference for records, streams and java.time, and the SpringBoot Reference for dependency injection, auto-configuration, Spring Data and Spring Security.

  1. Foundations: what Thymeleaf is, a first Spring Boot project, standalone use and the auto-configuration.

  2. Core template language: expressions, operators, utility objects, text and attributes, iteration, variables, links, inlining, textual modes and natural templates.

  3. Fragments and layouts: reuse of markup, the Layout Dialect and a component library.

  4. Spring MVC: controllers and views, forms, validation, conversion, internationalization, pagination and errors.

  5. Security: Spring Security integration, then escaping, restricted mode and the security advisories.

  6. Dynamic and interactive pages: fragment rendering, htmx, Alpine.js, push updates and reactive rendering.

  7. Assets and other outputs: styling, front-end assets and emails.

  8. Quality, extension and operations: testing, custom dialects, performance, tooling and migration.

mindmap root((Thymeleaf)) Foundations Natural templates Spring Boot setup Standalone engine Properties Core language Standard expressions Utility objects th attributes Iteration and conditionals Links and inlining Fragments and layouts Fragments Layout Dialect UI components Spring MVC Forms and binding Validation Conversion and i18n Pagination and errors Security Spring Security Escaping and CVEs Interactive pages Fragment rendering htmx Alpine.js SSE and WebSockets WebFlux Assets and output Tailwind and WebJars Emails Quality and operations Testing Custom dialects Performance Migration

What’s covered

Each page builds on the Bookshelf scenario, links every example to the official page it derives from, and ends with the sources it uses.

Foundations

Core template language

Fragments and layouts

Building web applications with Spring MVC

Security

Dynamic and interactive pages

Assets and other outputs

Quality, extension and operations

Where related material lives elsewhere on this site

The Thymeleaf pages link to existing material instead of repeating it, and cover only what Thymeleaf adds.

Topic Where it lives How the Thymeleaf section relates

Spring Boot, Spring Security, Spring Data, profiles, testing and reactive fundamentals

SpringBoot Reference, including Getting Started with Spring Boot, Spring Security, Spring Data JPA, Configuration and Profiles, Unit and Integration Testing, REST APIs with Spring MVC and WebFlux and Reactive Programming with Project Reactor

Thymeleaf pages link here instead of re-explaining Spring Boot, security, persistence, profiles, test slices or Reactor.

The choice between Thymeleaf, Vaadin and JSF

Server-Side Web UI Frameworks and Vaadin Reference, including Spring Boot Integration

The introduction compares Thymeleaf with Vaadin and links these pages for the decision table.

The Java language and persistence

Java Reference and Hibernate Reference

The getting-started page uses records, streams and java.time, and a JPA persistence layer for the scenario.

The same idea in other stacks

Django Templates, Template Partials & htmx, Blade Templates, Razor Syntax and Tag Helpers, Static Files, Templates & Frontend (FastAPI), Qute Templating, Server-side Templates (Axum) and htmx with Axum

The comparison table of the introduction and the htmx pages point to these pages.

Front end: HTML and CSS, Tailwind CSS, Bootstrap, accessibility

HTML & CSS Reference, Tailwind Reference, Bootstrap Reference and Web Accessibility

The styling, forms and validation pages link here for the CSS and accessibility theory.

Browser testing and cross-origin requests

E2E Testing in Real Browsers and What is CORS?

The testing page links the end-to-end page, and the htmx pages link the CORS theory.

OAuth 2.0 and OpenID Connect login

OAuth Reference, including Choosing an OAuth Flow and Spring Boot Integration: Overview

The Spring Security page links here for OAuth 2.0 login.

Architecture decisions

Starting a New Project, Layering: Isolating Backend and Frontend, Migration Path: From Single-Tenant to Multi-Tenant SaaS and Migration Path: From a Monolith to Microservices

The introduction links these pages for when a server-rendered front end is the right choice.

Containers, orchestration and cloud

Docker, Kubernetes and Cloud

The performance-and-production page shows only the Thymeleaf-specific parts.

Images and media

Media Optimization for the Web

Linked where image fragments and cover uploads are discussed.

Some related topics are tracked as separate issues and are only mentioned here: a comparison of backend and web frameworks (#263), chat, videoconference and WebSockets (#264), Playwright, Cypress and Selenium (#258) and IDE links (#116). PDF generation with JasperReports and iText is covered in the PDF Generation section, JSF in the JSF (JavaServer Faces) section, client-side Java with GWT in the GWT (Google Web Toolkit) section, and the JSP and Struts counterpart of this section in JSP & Struts.

Bibliography

Every source used to prepare this section is listed here, each linked to its official site. Individual pages list the subset they derive from under their own == References heading.

Books

The two books by Wim Deblauwe were consulted for concept coverage, narrative and structure only. They target older versions (Spring Boot 2.3 and Thymeleaf 3.0 for the first, Spring Boot 3.1 and htmx 1.9 for the second). No text, code listing, figure or sample project is taken from them: every example in this section is written against the current official documentation, and the pages point out where the books are outdated.

Official Thymeleaf documentation and resources

Published at thymeleaf.org/documentation.

Official documentation of related projects

Specifications, standards and security sources

The books are consulted references for concept coverage, narrative and structure; they are not reproduced here. The official documentation linked above is authoritative, and where the two differ, the documentation of the version you run prevails.

References