How to construct URLs in Thymeleaf

In this article, you'll learn how to construct different kinds of URLs in Thymeleaf templates. Thymeleaf is a popular server-side template engine for Java-based web and standalone environments.

Thymeleaf provides a so-called link expression (@{...}) to easily create static and dynamic URLs. The following examples explain how you can use this expression for different cases.

Absolute URLs

Absolute URLs are usually the ones that are pointed to other servers. These links start with the protocol name: http:// or https://. Unless you have an URL Rewriting filter configured on your server, these URLs will not be changed by the Thymeleaf template engine.

Here is an example:

<a th:href="@{}">About Me</a>

The rendered HTML should look like the below:

<a href="">About Me</a>

Context-Relative URLs

Context-relative is the most used URL format in web applications. Such URLs are relative to the web application root context configured on the server. For example, if your Spring Boot application is configured to use the webapp context path by setting the server.contextPath=/webapp property in the or application.yml file, the webapp will be the context name.

Context-relative URLs don't specify any protocol or host name. Instead, they simply start with / — relative to the current root directory:

<a th:href="@{/blog/what-is-thymeleaf}">What is Thymeleaf?</a>

For a web application that is configured to use webapp as a context name, the rendered HTML will look like the following:

<a href="/webapp/blog/what-is-thymeleaf">What is Thymeleaf?</a>

Without any context path configuration, the output will be the following:

<a href="/blog/what-is-thymeleaf">What is Thymeleaf?</a>

Server-Relative URLs

Server-relative URLs are very similar to Context-relative URLs except that they are not linked to any resource in your application's configured context. This allows you to link to a different context in the same server.

Here is an example:

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

Regardless of what your application context is, the Thymeleaf engine will ignore it and always render the following output:

<a href="topic/thymeleaf">Thymeleaf 101</a>

Protocol-Relative URLs

Protocol-relative URLs are like absolute URLs without any protocol (http:// or https://). They are commonly used for including static resources like JavaScript files, stylesheets, and images and directly point to an absolute path in the filesystem.

The following examples use the Protocol-relative URL format to include static resources:

<script th:src="@{//}"></script>
<link th:href="@{//}" rel="stylesheet">

Here is what the output looks like:

<script src="//"></script>
<link href="//" rel="stylesheet">

URLs With Parameters

To add query parameters to a URL, you have to specify them using parenthesis () after the URI path as shown below:

<a th:href="@{'thymeleaf')}">Search Thymeleaf</a>

The above statement will produce the following HTML output:

<a href="">Search Thymeleaf</a>

The Thymeleaf engine will automatically escape any special character used in the URL. To add multiple query parameters, separate them with commas as shown below:

<a th:href="@{'thymeleaf',num=12,lang=en)}">Search Thymeleaf</a>

Here is the HTML output now:

<a href=";num=12&amp;lang=en">Search Thymeleaf</a>

URL Fragment Identifiers

Fragment identifiers can be included in URLs, both with and without parameters, and in rendered HTML, they will always be included at the URL base.

For example, the following code snippet:

<a th:href="@{/blog#show-all(q='thymeleaf')}">Thymeleaf Tutorials</a>

Will render the following HTML:

<a href="/blog?q=thymeleaf#show-all">Thymeleaf Tutorials</a>

Using Expressions in URLs

Thymeleaf also supports expressions to build sophisticated URLs with dynamic parameters. In the following example, we use expressions to specify the values of query string parameters:

<a th:href="@{/posts/preview(id=${})}">View Post</a>

If ${} evaluates to 15, the rendered HTML will be the following:

<a href="/posts/preview?id=15">View Post</a>

URLs with Path Variables

Thymeleaf also allows you to use path variables to construct dynamic URLs. Path variables are typically used to pass a value as part of the URL. In the Spring Boot controller, you can retrieve these values using the @PathVariable annotation.

Here is an example that shows how you can pass a path variable in the URL:

<a th:href="@{/posts/{id}/preview(id=${})}">View Post</a>

The rendered HTML will look like the following:

<a href="/posts/15/preview">View Post</a>

Let us look at another example with multiple path variables in a URL:

<a th:href="@{/{username}/posts/{id}/preview/(username=${post.user.handle},id=${})}">View Post</a>

Here is the output of the above example:

<a href="/attacomsian/posts/15/preview">View Post</a>


That's it for constructing URLs in Thymeleaf. We have covered several ways to create different kinds of URLs using the Thymeleaf template engine.

Thymeleaf is a highly flexible server-side template engine that provides link expression as part of the standard dialects to build complex URLs with dynamic parameters.

Read Next: How to use Thymeleaf in Spring Boot

✌️ Like this article? Follow me on Twitter and LinkedIn. You can also subscribe to RSS Feed.

You might also like...

Digital Ocean

The simplest cloud platform for developers & teams. Start with a $200 free credit.

Buy me a coffee ☕

If you enjoy reading my articles and want to help me out paying bills, please consider buying me a coffee ($5) or two ($10). I will be highly grateful to you ✌️

Enter the number of coffees below:

✨ Learn to build modern web applications using JavaScript and Spring Boot

I started this blog as a place to share everything I have learned in the last decade. I write about modern JavaScript, Node.js, Spring Boot, core Java, RESTful APIs, and all things web development.

The newsletter is sent every week and includes early access to clear, concise, and easy-to-follow tutorials, and other stuff I think you'd enjoy! No spam ever, unsubscribe at any time.