About Thymeleaf


About Thymeleaf

Where does Thymeleaf come from? Is it made or backed by any software company?

Thymeleaf is Open Source Software originally created by a Spanish Software Engineer called Daniel Fernández and now developed and maintained by a great team of awesome people.

It is neither made nor backed by any software (or any other type of) company, and it is offered to the public totally free of charge, both in binary and in source code forms, under the Apache License 2.0.

Is it stable? Can it be considered production-ready?

Yes, all stable (non-beta) releases can be considered production-ready.

Does Thymeleaf offer any type of commercial support?

No, it does not. Official commercial support is not offered at the moment.

Who is using Thymeleaf?

Our 'Who is using Thymeleaf?' page contains a list of companies using Thymeleaf in their products, projects, websites, or even offering it as a part of their Professional Services portfolio. You will find some download figures there, too.

What is the project's versioning policy?

Thymeleaf version numbers have three components: x.y.z (like: 2.0.1).

  • x is the major version number. A change in this number means a rewrite of the core or architecture, or an important amount of changes in the library's APIs which might break backwards compatibility and/or legacy support.
  • y is the minor version number. A change in this number means a moderate set of changes has been applied, offering new features and improvements without changing APIs significantly and providing deprecation periods for all changed features in order to allow for a period of adaptation to the new interfaces.
  • z is the build/bugfix version number. A change in this number means the fix of some bugs or the addition of a series of performance or documentation improvements. Bugfix versions should modify no APIs and be therefore drop-in replacements for any previous version within the same major+minor version.

How can I contribute to Thymeleaf?

The first and most useful way to contribute to the project is by helping other users at popular places like StackOverflow. Building a better community is always priority number one.

You can also help Thymeleaf by promoting it: write on your blog, tweet, talk about it at your local JUG, or even simply discuss its advantages at your company/work and among your colleague developers. Help spread the word. Do you think your grandma might be interested? Tell her! :-)

If you are already doing your best at helping users and promoting, and still you feel that you could do more, there are a couple of things that are always useful:

  • Help testing. No amount of testing is enough testing, and your experience as a user is extremely valuable for building useful tests that Thymeleaf's developers might never think of. Thymeleaf has its own testing library and its own repository for tests, and there's always room for contributions there. If you want suggestions about what to test, we can guide you towards the areas that might better benefit from your help.
  • Help documenting. There's an "Articles" section at the documentation page that always welcomes new articles, especially if they include a nice example application. Your name will be displayed as author at the article, so that you can add it to your resume ;), but of course we will ask you for a high level of quality and a good knowledge of the English language. We keep a list of topic suggestions here, but you can always propose your own to the Team.

What else? Well, of course you can bring your own ideas! You can create a GitHub issue or just send an email directly to the Team. We will be happy to review and discuss your ideas with you. Please don't just upload a Pull Request with your favourite feature without previous discussion with the team — Thymeleaf is a complex project and requires a certain level of organization, and we might not be able to accept your code even if you put a lot of effort on it (or even if your idea is good!).

Finally, please note that all artifact contributions to Thymeleaf (code, documentation...) are regulated by certain Terms and Conditions. Before accepting any patches, articles, etc. from you we will require you to explicitly agree on this terms (an email or a github comment will do).

How do you pronounce 'thymeleaf'?

In case you are unsure, 'Thymeleaf' is pronounced like this: /ˈtaɪmˌlɪːf/


Is Thymeleaf a web framework?

No, it isn't. It is a template engine.

Template engines play a key role in web frameworks, though, and are one of its most important components as they are in charge of producing the user interface or view layer (usually in XHTML or HTML form).

Spring MVC, Struts or Apache Wicket are examples of web frameworks, whereas JSP, Velocity or FreeMarker are examples of template engines.

What types of templates can Thymeleaf process?

Thymeleaf templates can be:

  • HTML (HTML5, XHTML 1.0/1.1, HTML 4)
  • XML
  • TEXT (plain text)
  • JAVASCRIPT (.js files)
  • CSS (.css files)

Can Thymeleaf be used as a complete substitute for JSP and JSTL?

Absolutely. Not only it can, but we strongly encourage you to do so. Have a look at our Thymeleaf vs. JSP article if you want to learn how these two technologies compare.

How does Thymeleaf compare with other template engines like Velocity or FreeMarker?

Both Velocity and FreeMarker are terrific pieces of software, but they approach the templating problem with a philosophy quite different to that of Thymeleaf.

Thymeleaf makes a strong stress on natural templating —allowing templates to be working prototypes, which the other two do not allow—, and its syntax tries to be (arguably) cleaner and more in tune with the current trends in web development. Also, from an architectural standpoint, both Velocity and FreeMarker work as sequential text processors whereas Thymeleaf is based on markup parsing techniques. This allows Thymeleaf to take advantage of interesting features specific to markup-based environments, especially the web.

Anyway, the best way to compare these technologies is to use them yourself and feel which one suits you best.

Can it be used outside web applications in non-web environments?

Yes it can. Although Thymeleaf (especially its Standard dialects) offers many features that are especially useful in web environments, it can be used for processing non-web HTML or XML documents (data XML, for example) or other types of templates that are not meant for being sent via HTTP (for example, text/HTML email content).

I don't use Spring at all. Can I still use Thymeleaf?

Absolutely. Thymeleaf offers nice integration with Spring MVC through its SpringStandard dialect (included in the thymeleaf-spring3, thymeleaf-spring4 and thymeleaf-spring5 packages), but Spring integration is completely optional and the Standard dialect is in fact meant to be used without Spring.

How can I use a SNAPSHOT release of Thymeleaf?

From time to time, Thymeleaf will produce a snapshot release that will allow you to test new or being-developed features. These are non production ready releases, but will be stable enough for most testing purposes, and will enable you to try new features before they are generally available.

In order to use snapshot releases, you need to add the Sonatype OSS Snapshots repository in your Maven pom.xml file, like this:

Also, you will have to modify your Thymeleaf dependency/ies to use a snapshot version, which usually consists of the version number of the next release (not the current one), followed by -SNAPSHOT. For example, if 3.1.1.RELEASE is the latest published stable release, snapshots will probably appear under the 3.1.2-SNAPSHOT or even 3.2.0-SNAPSHOT version numbers:

How is thymeleaf tested?

Thymeleaf has its own testing framework, called thymeleaf-testing. This testing framework not only allows the Thymeleaf Team to easily test the library, but also allows users to test the view layer of their applications. You can explore it at GitHub.

Making use of this testing framework, Thymeleaf maintains another GitHub repository completely devoted to tests. Tests, tests, and more tests. It's the thymeleaf-tests repository that you can find here. Want some figures? As of June 2014 the thymeleaf-tests repository contained more than 1,300 test files, adding up to more than 37,000 lines of testing code.

Besides, we use Travis CI for continuous integration, thanks to what every release is published after being tested in no-Spring, Spring 3.0, Spring 3.1, Spring 3.2 and Spring 4.0 environments, with Java 6, 7 and 8 (unfortunately Travis does not support Java 5, so we test that manually).