Route Parameters

Accessing the Route Parameter Value
Optional Parameters
Wildcard Parameters
Try It

In this guide, you’ll learn how to create a view that accepts a single route parameter. You’ll also explore the differences between optional and wildcard route parameters. Finally, a mini-tutorial will help you apply these concepts in a real Vaadin application.

Accessing the Route Parameter Value

To pass a route parameter to a Flow view, implement the HasUrlParameter<T> interface. This interface requires a type argument, which can be Long, Integer, String, or Boolean. It defines the setParameter() method, which receives the route parameter when the view is navigated to.

For example, to create a CustomerView that takes a customer ID as a parameter, use the following code:

@Route("customers")
public class CustomerView extends Main implements HasUrlParameter<String> {

    @Override
    public void setParameter(BeforeEvent event, String parameter) {
        setText("Customer ID: " + parameter);
    }
}

Now, if you navigate to /customers/cu12345, the router calls setParameter() with "cu12345" as the parameter value.

Optional Parameters

By default, route parameters are required. In the example above, if you try to navigate to /customers, the router returns a 404 Not Found error.

To make a route parameter optional, add the @OptionalParameter annotation:

@Route("customers")
public class CustomerView extends Main implements HasUrlParameter<String> {

    @Override
    public void setParameter(BeforeEvent event, @OptionalParameter String parameter) {
        if (parameter == null) {
            showCustomerList();
        } else {
            showCustomerWithId(parameter);
        }
    }

    private void showCustomerList() {
        // ...
    }

    private void showCustomerWithId(String customerId) {
        // ...
    }
}

Now, if you now navigate to /customers, the router calls setParameter() with null as the parameter value.

Wildcard Parameters

By default, a route parameter captures only a single URL segment. For example, if your customers route expects a string parameter, navigating to /customers/cu1234/edit would result in a 404 Not Found error.

To capture multiple URL segments as a single parameter, use the @WildcardParameter annotation:

@Route("customers")
public class CustomerView extends Main implements HasUrlParameter<String> {

    @Override
    public void setParameter(BeforeEvent event, @WildcardParameter String parameter) {
        if (parameter.isEmpty()) {
            showCustomerList();
        } else {
            // Extract the and process the segments from the parameter
        }
    }

    private void showCustomerList() {
        // ...
    }
}

Now, navigating to /customers/cu1234/edit passes "cu1234/edit" as the parameter value.

Note	An empty wildcard parameter is an empty string (`""`), while an empty optional parameter is `null`. So, navigating to `/customers` calls `setParameter()` with `""` instead of `null`.

If you’re considering wildcard parameters because you need multiple route parameters, Route Templates may be a better solution.

Try It

In this mini-tutorial, you’ll create a view that implements HasUrlParameter and experiment with @OptionalParameter and @WildcardParameter.

Set Up the Project

First, generate a walking skeleton with a Flow UI, open it in your IDE, and run it with hotswap enabled.

Create the View

Create a new package [application package].tutorial.ui.view, and in it a new class called ParameterView:

import com.vaadin.flow.component.html.Main;
import com.vaadin.flow.router.BeforeEvent;
import com.vaadin.flow.router.HasUrlParameter;
import com.vaadin.flow.router.Route;

@Route("parameter")
public class ParameterView extends Main implements HasUrlParameter<String> {

    @Override
    public void setParameter(BeforeEvent event, String parameter) {
        setText("Parameter: " + parameter);
    }
}

Open your browser and go to: http://localhost:8080/parameter/hello

You should see:

Parameter: hello

Make the Parameter Optional

Now navigate to: http://localhost:8080/parameter

You should see a Could not navigate to 'parameter' error.

To fix this, modify the class by adding @OptionalParameter:

import com.vaadin.flow.component.html.Main;
import com.vaadin.flow.router.BeforeEvent;
import com.vaadin.flow.router.HasUrlParameter;
import com.vaadin.flow.router.OptionalParameter;
import com.vaadin.flow.router.Route;

@Route("parameter")
public class ParameterView extends Main implements HasUrlParameter<String> {

    @Override
    public void setParameter(BeforeEvent event, @OptionalParameter String parameter) {
        setText("Parameter: " + parameter);
    }
}

Refresh the browser at: http://localhost:8080/parameter

Now you should see:

Parameter: null

Capture Multiple Segments with a Wildcard

Try navigating to: http://localhost:8080/parameter/hello/world

You’ll get a Could not navigate to 'parameter/hello/world' error.

Now, replace @OptionalParameter with @WildcardParameter:

import com.vaadin.flow.component.html.Main;
import com.vaadin.flow.router.BeforeEvent;
import com.vaadin.flow.router.HasUrlParameter;
import com.vaadin.flow.router.Route;
import com.vaadin.flow.router.WildcardParameter;

@Route("parameter")
public class ParameterView extends Main implements HasUrlParameter<String> {

    @Override
    public void setParameter(BeforeEvent event, @WildcardParameter String parameter) {
        setText("Parameter: " + parameter);
    }
}

Refresh the page, and now you’ll see:

Parameter: hello/world

If you navigate to: http://localhost:8080/parameter

You’ll see:

Parameter:

Since it’s a wildcard parameter, it is treated as an empty string instead of null.

Final Thoughts

Now you’ve successfully implemented route parameters in Flow. You learned how to:

Pass a single route parameter to a view.
Make parameters optional.
Use wildcard parameters to capture multiple URL segments.

You’re now ready to use route parameters in real Vaadin applications. Try customizing the ParameterView class to do something more than printing the parameter value!

Docs