Constructing URLs in Thymeleaf

1. Introduction

Thymeleaf provides an easy way to create URLs using link expressions @{...}. In this article, we will present several methods to build URLs used for links and to include external resources for your application.

2. Absolute URLs

Absolute URLs are used to build links that pointed to other servers. They start with a protocol name http:// or https://. Unless you have URL Rewriting filter configured at your server, they will not be changed by Thymeleaf engine.

In this example we create an absolute URL to https://frontbackend.com/tag/thymeleaf:

<a th:href="@{https://frontbackend.com/tag/thymeleaf}">Thymeleaf</a>

The output will be the following:

<a href="https://frontbackend.com/tag/thymeleaf">Thymeleaf</a>

3. Context-relative URLs

This kind of URLs are the most used ones in web applications. Context-relative URLs are relative to the web application root context configured on the server. For example, if your Spring Boot application using context path, so there is a server.contextPath=/myapp parameter in your application.properties, the myapp will be the context name.

Context-relative URLs start with /.

For example link providated like the following:

<a th:href="@{/tag/thymeleaf}">Thymeleaf</a>

for application served on myapp context, the output will look like the following:

<a href="/myapp/tag/thymeleaf">Thymeleaf</a>

for application served without root context, the output will be the following:

<a href="/tag/thymeleaf">Thymeleaf</a>

4. Server-relative URLs

Server-relative URLs are similar to Context-related URLs but in this case, you can point to a different context, not the root configured on an application server.

In the following example althought your app server is running on myapp context, using that structure:

<a th:href="@{~/tag/thymeleaf}">Thymeleaf</a>

will ignore it and produce the following output:

<a href="/tag/thymeleaf">Thymeleaf</a>

5. Protocol-relative URLs

Protocol-relative URLs are typically used to include external resources like styles, scripts, images, etc. This kind of URL works like an absolute path in filesystem and keep the configured protocol: HTTP or HTTPS.

The following example used Protocol-relative URL to include script.js on https://frontbackend.com website:

<script th:src="@{//frontbackend.com/script.js}"></script>

it will render unmodified:

<script src="//frontbackend.com/script.js"></script>

6. URLs with parameters

To add query parameters to a URL you have to put them in parentheses ( ).

For example one query parameter added to an URL will look like the following:

<a th:href="@{/tags(tag='thymeleaf')}">thymeleaf</a>

This will produce the following output:

<a href="/tags?tag=thymeleaf">thymeleaf</a>

Note that any special character used will be HTML-escaped.

To provide many parameters, separate them with commas:

<a th:href="@{/tags(tag='thymeleaf',order=1,sort=true)}">thymeleaf sorted</a>

Above example will be rendered like the following:

<a href="/tags?tag=thymeleaf&amp;order=1&amp;sort=true">thymeleaf sorted</a>

7. URL fragment identifiers

Fragment identifiers can be included in URLs, and in rendered HTML they will always be included.

For example the following code:

<a th:href="@{/tags#all_tags(action='show')}">tags</a>

will be rendered to the following html:

<a href="/tag?action=show#all_tags">tags</a>

8. Using expressions in URLs

Thymeleaf allows you to provide a complex URL built with dynamic parameters.

In the following example we use ${customer.id} expression and ${customer.active} condition to create a dynamic link inside an application:

<a th:href="@{/customers(id=${customer.id},action=(${customer.active} ? 'show_active' : 'show_limited'))}">customer details</a>

When ${customer.id} evaluated to 1000and ${custoemr.active} is true then rendered output will be the following:

<a href="/customers?id=1000&amp;action=show_active">customer details</a>

9. Conclusion

In this article, we presented several ways to create URLs in Thymeleaf templates. Thymeleaf gives mechanisms to build complex URLs with dynamic parameters.