Routing and Navigation

Routing and navigation are core concepts for any web application or site. In Vaadin 10 and later this has been completely reinvented. In Vaadin 8 and 7 Navigator only supported single-level navigation, had limited support for parameters and did not support HTML5 History API until Vaadin 8.2.

This document only outlines the core concept and how it differs from the old Navigator. To get the best picture on the capabilities of the new Router, you should visit the Router documentation.

The Router API allows building robust and complex application structures with hierarchies, error handling and view access control by using lifecycle events.

Unlike in Vaadin 8 where route configuration was made for each UI instance separately, in Vaadin 14 the routes are configured declaratively on each navigation target and are the same for the entire application:

@Route(value = "company", layout = MainLayout.class)
public class CompanyView extends Composite<Div> {
     // Implementation omitted
}

Thus, when migrating from using Navigator, any View from Vaadin 8 can be migrated to Vaadin 14 by removing the registration from the now optional UI class and instead applying the @Route annotation the class. Note that there is no View interface in Vaadin 14, but instead the class must be a Component!

To receive an event when the user navigates to or from a view, make it implement one of BeforeEnterObserver, BeforeLeaveObserver or AfterNavigationObserver interfaces instead of the enter and beforeLeave methods from View in Vaadin 8. BeforeLeaveEvent.postpone() can be used to postpone or cancel navigation to achieve the same results as selectively calling ViewBeforeLeaveEvent.navigate() in Vaadin 8.

Instead of manually constructing URLs and using ViewChangeEvent.getParameters() to find parameter values, you can use UI.navigate(NavigationTargetClass.class) and have your view implement the HasUrlParameter interface.

The ViewDisplay concept has been replaced in Vaadin 14 with the RouterLayout interface, but now it is possible to have nested hierarchies, by using the @ParentLayout annotation to set one RouterLayout class as the parent of another.

There is no ViewProvider in Vaadin 14 as it is not needed.

With the HTML5 History API, it is possible to have deep-linking and use proper navigation state and parameters for the navigation targets. Optional parameters are also supported since Vaadin 10. However, it is no longer possible to use the fragment style (#!) navigation state from Vaadin 8 as the fragment is not intended to be used on the server side at all, but just be a browser feature for navigation inside a page.

It is very much recommended to take a look at the router documentation to get full understanding on how to structure your Vaadin 14 application.

Updated 2021-03-09  Edit this article