Docs

Docs

Route Templates

Learn how to use route templates in Vaadin.

In this guide, you’ll learn how to create a view that accepts multiple route parameters using route templates. You’ll also learn how to use modifiers and regular expressions to tweak the behavior of the route parameters.

Using a single route parameter is easier than using a route template. If you can get the job done using the HasUrlParameter<T> interface, use that instead.

Copy-Paste into Your Project

If you want to quickly try out route templates in your Vaadin application, copy-paste the following code into a new Java class named RouteTemplateView in your project’s main package:

Source code
RouteTemplateView.java

For more detailed instructions on how to use route templates, continue reading below.

Specifying Multiple Route Parameters

To specify multiple route parameters, you use a route template instead of a static path when declaring a @Route. In a route template, one or more of the URL segments is a route parameter. Route parameters must follow the following syntax:

:parameter_name[modifier][(regex)]

The following sections explain this syntax in detail.

The following example demonstrates a view with two route parameters: customerId and action:

Source code
Java
@Route("customer/:customerId/:action")
public class CustomerView extends Main {
    ...
}

Now, if you navigate to /customer/cu12345/edit, the router renders the CustomerView with the following route parameter values:

  • customerId → "cu12345"

  • action → "edit"

Accessing Route Parameter Values

To access the route parameter values, your view must implement the BeforeEnterObserver interface. This interface defines the beforeEnter() method, which is called by the router before navigating to the view. Inside the method, you can access the route parameters:

Source code
Java
@Route("customer/:customerId/:action")
public class CustomerView extends Main implements BeforeEnterObserver {

    private static final String PARAM_CUSTOMER_ID = "customerId"; 1
    private static final String PARAM_ACTION = "action";

    @Override
    public void beforeEnter(BeforeEnterEvent event) {
        var customerId = event.getRouteParameters().get(PARAM_CUSTOMER_ID).get();
        var action = event.getRouteParameters().get(PARAM_ACTION).get();
        // Process the parameters
    }
    ...
}

  1. Tip: To improve readability and maintainability, declare route parameter names as constants near the @Route annotation.

The RouteParameters class defines methods for accessing route parameter values as String, Integer, or Long. They all return an Optional<T>.

In the example above, both customerId and action are required, so you can assume that those route parameter values are never empty. If you try to navigate to /customer or /customer/cu12345, the router returns a 404 Not Found error.

Optional Route Parameters

By default, all route parameters are required. To make a route parameter optional, use the ? modifier:

Source code
Java
@Route("customer/:customerId/:action?") 1
public class CustomerView extends Main implements BeforeEnterObserver {

    private static final String PARAM_CUSTOMER_ID = "customerId";
    private static final String PARAM_ACTION = "action";

    @Override
    public void beforeEnter(BeforeEnterEvent event) {
        var customerId = event.getRouteParameters().get(PARAM_CUSTOMER_ID).get();
        var action = event.getRouteParameters().get(PARAM_ACTION).orElse(null); 2
        // Process the parameters
    }
    ...
}

  1. The action route parameter is now optional.

  2. The route parameter value can now be empty.

Now, if you navigate to /customer/cu12345, the action route parameter is empty. You can handle empty parameters by providing a default value, redirecting users, or displaying an error message.

When using multiple optional route parameters, values are assigned from left to right. If a parameter is missing, the next available value shifts left to fill its place. For instance, consider an application with the route customer/:customerId?/:action?:

  • /customer → Calls the customer route with no route parameters at all.

  • /customer/cu12345 → Calls the customer route with "cu12345" as the value of customerId.

  • /customer/cu12345/edit → Calls the customer route with "cu12345" as the value of customerId, and "edit" as the value of action.

Wildcard Route Parameters

By default, a route parameter captures only a single URL segment. However, the last segment in the route template can be declared a wildcard route parameter. This means that the route parameter captures all the segments in its place. A wildcard route parameter is always optional.

To denote a route parameter a wildcard, use the * modifier:

Source code
Java
@Route("api/:path*")
public class ApiViewer extends Main implements BeforeEnterObserver {

    @Override
    public void beforeEnter(BeforeEnterEvent event) {
        var path = event.getRouteParameters().get("path").orElse("");
        // Process the path
    }
}

Now, if you navigate to api/com/vaadin/flow/, the path route parameter has the value "com/vaadin/flow".

You can also access the URL segments captured by a wildcard route parameter individually:

Source code
Java
@Route("api/:path*")
public class ApiViewer extends Main implements BeforeEnterObserver {

    @Override
    public void beforeEnter(BeforeEnterEvent event) {
        List<String> segments = event.getRouteParameters().getWildcard("path");
        // Process the segments
    }
}

Now, if you navigate to the same URL, the segments variable contains the list ["com", "vaadin", "flow"].

Note
 If a route parameter is missing, getWildcard() returns an empty list.

Constraining Route Parameter Values with Regular Expressions

In all the examples discussed, the route parameters accept any value. However, a specific value is often expected for a route parameter and the view should be shown only when that specific value is present in the URL. You can do this by defining a regular expression for the route parameter. This reduces the need for validation and sanitation of route parameter values in the beforeEnter() method.

Note
 The syntax of the regular expressions is checked at application startup. If there is an error, the application fails to start.

In the following example, the customerId route parameter is constrained to an integer between 1 and 9 digits, and the action route parameter can be either "view", "edit", or empty:

Source code
Java
@Route("customer/:customerId([0-9]{1,9})/:action?(view|edit)")
public class CustomerView extends Main {
    ...
}

If you navigate to a URL that doesn’t meet these constraints, you’ll receive a 404 Not Found error.

When you specify constraints on wildcard route parameters, the regular expression is applied to every segment that would be captured by the route parameter. If any of the segments fails to match the expression, the whole route template fails to match the URL, and you’ll get a 404 Not Found error.