How to Build Navigation and Layouts in Vaadin Flow Apps
Define routes with annotations, wrap them in a shared layout with a side menu, pass URL parameters and guard views before they open.

Navigation in Vaadin Flow is driven by annotations, and the details decide how pleasant a growing application feels. A route is a class annotation, so the compiler and the IDE can follow it. A layout wraps a group of views so the header and menu are written once. Navigating by class instead of by string means a renamed view is caught at compile time. This post builds a main layout with a side menu, two views and a parameterized page, then adds an entry guard and a way to stop users leaving unsaved work. It is for Vaadin 25. The first project is in the Vaadin tutorial, and the overview is in Building web UIs in pure Java with Vaadin.
Two views
@Route(value = "customers", layout = MainLayout.class)
@PageTitle("Customers")
public class CustomerListView extends VerticalLayout {
public CustomerListView() {
add(new H2("Customers"));
}
}@Route(value = "orders", layout = MainLayout.class)
@PageTitle("Orders")
public class OrderListView extends VerticalLayout {
public OrderListView() {
add(new H2("Orders"));
}
}The path comes from value, and an empty string is the root. @PageTitle sets the browser tab title, which also becomes the label in history and bookmarks, so give every view one. Flow finds routes by scanning the classpath at startup, so there is no registry to update when you add a view.
A layout with a side menu
public class MainLayout extends AppLayout {
public MainLayout() {
SideNav nav = new SideNav();
nav.addItem(new SideNavItem("Customers", CustomerListView.class));
nav.addItem(new SideNavItem("Orders", OrderListView.class));
addToDrawer(nav);
addToNavbar(new DrawerToggle(), new H1("Admin"));
}
}AppLayout already implements RouterLayout. A view that names this class as its layout is rendered inside the layout's content area, and the layout stays in place while the view changes. That is why navigation feels like a single-page application although the server drives it. Layouts can nest: give a layout its own @ParentLayout and the chain wraps from the inside out. A SideNavItem takes the view class, so the compiler tracks renames and the menu cannot point at a path that no longer exists.
Navigate in code and in markup
Button open = new Button("Open orders",
e -> UI.getCurrent().navigate(OrderListView.class));For a link inside the page, use RouterLink:
add(new RouterLink("Orders", OrderListView.class));A RouterLink renders a real anchor that navigates without reloading the page, and its href is right even when the application runs under a context path, which a hand-written string would get wrong. Prefer both forms over navigate("orders") with a literal. A string path is the form that breaks silently when someone changes the route.
Passing values in the URL
@Route(value = "customer", layout = MainLayout.class)
public class CustomerDetailView extends VerticalLayout
implements HasUrlParameter<Long> {
@Override
public void setParameter(BeforeEvent event, Long id) {
removeAll();
add(new H2("Customer " + id));
}
}A request for /customer/42 calls setParameter with 42, converted to a Long. From code, navigate with ui.navigate(CustomerDetailView.class, 42L). For a value that may be absent, annotate the parameter with @OptionalParameter. Named query parameters, such as ?tab=history, come from event.getLocation().getQueryParameters(). Because the view can be opened directly from a bookmarked address, setParameter must cope with an id that does not exist: forward to a not-found view instead of showing an empty page.
Guarding a view on the way in
public class AdminView extends VerticalLayout implements BeforeEnterObserver {
@Override
public void beforeEnter(BeforeEnterEvent event) {
if (!security.isAdmin()) {
event.forwardTo(CustomerListView.class);
}
}
}forwardTo shows another view and keeps the target URL out of the history, and rerouteTo changes the target. Both stop the original navigation. Use this for convenience redirects, such as sending a signed-out user to the login view.
Be clear about what it is. Hiding a view is not security. A determined user can still call whatever the server exposes, so authorization must also be enforced where the data is served, in the service methods behind the view. With Spring Security, Vaadin's integration restricts views by role with annotations on the view class, which is the right place for the rule. See Vaadin with Spring Boot.
Leaving a view with unsaved work
BeforeLeaveObserver lets a view postpone a navigation, so the user is asked before losing an edit:
@Override
public void beforeLeave(BeforeLeaveEvent event) {
if (form.hasChanges()) {
BeforeLeaveEvent.ContinueNavigationAction action = event.postpone();
ConfirmDialog dialog = new ConfirmDialog("Discard changes?", "", "Discard",
e -> action.proceed());
dialog.open();
}
}postpone() returns an action; calling proceed() later resumes the navigation the user asked for. The same check does not cover closing the browser tab, which needs a browser-side beforeunload handler.
Aliases, deep links and the back button
@RouteAlias gives a view more than one path, which is how you keep an old URL working after a rename. A deep link works because the server can rebuild the whole view from the address, so a bookmarked /customer/42 opens the right page after a restart. The browser's back button works too, since Flow updates the history entry on each navigation. If back misbehaves, the usual cause is a view that reads state set by the previous one instead of by the URL.
Not-found, errors and the login view
Unknown paths need a page. Implement HasErrorParameter<NotFoundException> on a view, and Flow shows it for any address with no route, so users get a friendly page and a link home instead of a stack trace. The same mechanism handles other exceptions: a view that implements HasErrorParameter for your own AccessDeniedException can show a "not allowed" page.
The login view is an ordinary route with no layout, so the menu and navbar do not appear. A common arrangement is a separate LoginView annotated with @Route("login") and @AnonymousAllowed, and the guard sends unauthenticated users there. Remember to restore the original target after a successful login, by storing the requested location before the redirect, or users always land on the home page and lose their place.
Menu from the routes
Writing the menu by hand works for a handful of views and drifts after that. Flow can list the registered views, and a loop over them builds the side navigation, so a new view appears in the menu when you add the annotation. If you want an ordering or a hidden entry, put the metadata on the view with a small custom annotation and read it in the loop. The saving is not the typing: it is that the menu can no longer disagree with the routes.
Keep routes unique and titled
Two views that claim the same path produce an error at startup, and a view without a title shows the application name for every page in the browser history. A small test catches the first, and an annotation handles the second:
@Route(value = "orders", layout = MainLayout.class)
@PageTitle("Orders")
public class OrdersView extends VerticalLayout { /* ... */ }class RoutesTest {
@Test
void everyRouteIsUnique() {
var scanner = new ClassPathScanningCandidateComponentProvider(false);
scanner.addIncludeFilter(new AnnotationTypeFilter(Route.class));
Map<String, String> seen = new HashMap<>();
for (BeanDefinition candidate : scanner.findCandidateComponents("dev.javahacks.shop.ui")) {
Class<?> view = ClassUtils.resolveClassName(candidate.getBeanClassName(), getClass().getClassLoader());
String path = view.getAnnotation(Route.class).value();
String previous = seen.put(path, view.getSimpleName());
assertNull(previous, "path '" + path + "' is used by " + previous + " and " + view.getSimpleName());
}
}
}For a title that depends on the data, such as the order number, implement HasDynamicTitle and return it from getPageTitle(). Keep the path strings in one place as constants when several views link to each other, so a rename is one edit, and so that a link in a menu and the @Route on its target cannot drift apart.
What this does not replace
There is no client-side router to maintain, which is the point of Flow, and it means every navigation is a round trip to the server. For a UI that is mostly client logic, consider Hilla instead. The routing documentation and the router layouts chapter describe the remaining options.


