Documentation

Documentation versions (currently viewingVaadin 23)
New Acceleration Kits: Observability Kit, SSO Kit, and Swing Kit. Read the blog post.

Routing and Navigation

Vaadin applications consist of one or more views and routing defines how URL addresses are mapped to those views. Navigating around 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.

Sometimes 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
Route Parameters
Route parameters are variable parts of the URL segment that can be used to pass extra information to a given route
Updating URL Parameters without Navigation
To preserve deep linking, the developer sometimes needs to maintain the route parameters and query parameters manually
Navigation Lifecycle
Router Layouts and Nested Router Targets
Retrieving Routes
Router Exception Handling
Getting Registered Routes
Updating Page Title on Navigation
Registering Routes Dynamically
Additional Guides
Additional guides related to routing and navigation