Documentation

Documentation versions (currently viewingVaadin 24)

Routing & Navigation

Explains routing, how URLs are mapped to views, and navigating applications.

Vaadin applications consist of one or more views. Routing defines how URL addresses are mapped to those views. Navigating the application works together with routing.

Views in Vaadin are larger components that present logical parts of your UI. They are typically composed of other smaller components and help you structure and reuse your UI code. Routing in Vaadin means mapping views into specific URLs and maintaining meaningful deep linking. Deep linking allows your users (by copy-pasting the current URL from their browser) and other applications to share direct links to a specific view and state in your Vaadin UI.

A route in Vaadin lingo means a view mapped to a specific URL. URLs can also contain route parameters or query parameters that views can utilize to configure their internal state further.

The user navigates between views in your application by interacting with UI elements such as buttons, links, and menus. Vaadin maintains the proper deep linking URL in your end user’s browser when using the framework’s built-in mechanisms for navigation.

Routing and navigation isn’t intended to be the primary mechanism to interact with different parts of your UI or to maintain the state of the application. Directly changing the state of components and adding/removing them from the UI using Java APIs is easier and more efficient. In fact, if deep linking isn’t needed, even a large Vaadin application can ignore routing and navigation APIs for simplicity and only route the entry view to the root URL of the application. However, routing and navigation APIs in Vaadin help you achieve a decent level of deep linking. Therefore, you should route at least the top-level views to different URLs and then utilizing more advanced features like parameters and nested routes for views where you need better deep linking.

Occasionally, proper deep linking requires the developer to manually maintain the URL parameters. For example, the UI state can lose parity with the URL shown in the browser by user interaction within the view, like changing search filters, or by a message arriving through another thread. Also, other views may be passing data directly using Java APIs, instead of using URL parameters. In these cases, the routing mechanism can’t update the URL automatically.

Topics

Defining Routes
Using the Route annotation to define route URLs.
Navigating Between Routes
Ways in which to switch between routes or views.
Route Parameters
How to pass extra information to a route using route parameters.
Updating URL Parameters without Navigation
How to update URL parameters manually and without navigation.
Navigation Lifecycle
Explains the events that happen during a user initiated navigation between two routes.
Router Layouts & Nested Router Targets
Explains router layouts and nested router targets.
Retrieving Routes
How to retrieve the generated route for registered navigation targets.
Router Exception Handling
Handling router exceptions with the Router class.
Getting Registered Routes
How to retrieve all registered routes.
Updating Page Title on Navigation
How to update a page title during navigation.
Registering Routes Dynamically
How to register routes and route templates, dynamically.
Additional Guides
Additional guides related to routing and navigation.