Introduction

In Thymeleaf, path variables inside th:href are created by using a URI template and then supplying values in parentheses. The syntax is compact once you know it, but it is easy to confuse with query-parameter syntax if you have only seen simpler @{/path} examples.

The Core Syntax

The basic pattern is:

<a th:href="@{/users/{id}(id=${user.id})}">View</a>

This produces a URL such as /users/42 when user.id is 42.

The rule is:

• put the path variable placeholder in braces inside the path
• provide the replacement value in parentheses after the path

That is how Thymeleaf maps model data into path variables.

A Complete Example

Controller:

1@GetMapping("/users")
2public String users(Model model) {
3    model.addAttribute("user", new User(42L, "Ava"));
4    return "users";
5}
6
7public record User(Long id, String name) {}

Template:

<a th:href="@{/users/{id}(id=${user.id})}" th:text="${user.name}"></a>

Rendered result:

<a href="/users/42">Ava</a>

That is the normal Thymeleaf pattern for Spring MVC path-variable links.

Multiple Path Variables

You can provide more than one variable.

<a th:href="@{/teams/{teamId}/users/{userId}(teamId=${team.id}, userId=${user.id})}">
  Details
</a>

This becomes something like /teams/7/users/42.

The names in the parentheses must match the placeholders in the path template.

Path Variables vs Query Parameters

Do not confuse this with query-parameter syntax. Query parameters are written like this:

<a th:href="@{/users(id=${user.id})}">Search</a>

That produces /users?id=42, not /users/42.

So if you want REST-style path segments, keep the placeholder inside the path itself.

When Context Paths Matter

Thymeleaf URL expressions are context-aware. If your application is deployed under a context path such as /app, the generated link will reflect that automatically. That is one reason to prefer th:href over manually concatenating strings.

String concatenation works, but it is more fragile and gives up Thymeleaf's URL handling.

This matters because many Spring MVC routes are designed around path variables. Using the matching Thymeleaf syntax keeps the template aligned with the controller mapping instead of manually stitching URL strings together.

Common Pitfalls

The biggest mistake is putting the variable only in the parentheses and forgetting the placeholder in the path. That generates a query parameter, not a path variable.

Another mistake is mismatching the placeholder name and the variable name in the parameter list.

A third mistake is building URLs by string concatenation instead of using Thymeleaf URL expressions. The template engine already solves this problem cleanly.

Summary

• Use @{/path/{var}(var=${value})} for Thymeleaf path variables in th:href.
• The placeholder goes in the path, and the value mapping goes in parentheses.
• Multiple path variables are supported by listing each mapping explicitly.
• Query-parameter syntax is different and produces a different URL shape.
• Prefer Thymeleaf URL expressions over manual string concatenation for links.