0
# Routing and Navigation
1

2
Vaadin's routing system provides declarative, annotation-based navigation for single-page applications. It supports parameterized routes, nested layouts, navigation guards, and programmatic navigation.
3

4
## Core Imports
5

6
```java
7
// Route definition annotations
8
import com.vaadin.flow.router.Route;
9
import com.vaadin.flow.router.PageTitle;
10
import com.vaadin.flow.router.Menu;
11
import com.vaadin.flow.router.ParentLayout;
12
import com.vaadin.flow.router.ErrorRoute;
13

14
// Navigation components
15
import com.vaadin.flow.router.RouterLink;
16
import com.vaadin.flow.component.html.Anchor;
17

18
// Navigation parameters and events
19
import com.vaadin.flow.router.HasUrlParameter;
20
import com.vaadin.flow.router.OptionalParameter;
21
import com.vaadin.flow.router.WildcardParameter;
22
import com.vaadin.flow.router.BeforeEvent;
23
import com.vaadin.flow.router.BeforeEnterEvent;
24
import com.vaadin.flow.router.BeforeLeaveEvent;
25
import com.vaadin.flow.router.AfterNavigationEvent;
26

27
// Navigation lifecycle interfaces
28
import com.vaadin.flow.router.BeforeEnterObserver;
29
import com.vaadin.flow.router.BeforeLeaveObserver;
30
import com.vaadin.flow.router.AfterNavigationObserver;
31

32
// Navigation control and events
33
import com.vaadin.flow.router.NavigationTrigger;
34
import com.vaadin.flow.router.Location;
35
import com.vaadin.flow.router.LocationChangeEvent;
36
import com.vaadin.flow.router.ContinueNavigationAction;
37

38
// Route layouts
39
import com.vaadin.flow.router.RouterLayout;
40
import com.vaadin.flow.component.HasElement;
41

42
// Router and configuration
43
import com.vaadin.flow.router.Router;
44
import com.vaadin.flow.router.RouteConfiguration;
45
import com.vaadin.flow.router.RouteData;
46
import com.vaadin.flow.router.NavigationResult;
47

48
// Route parameters
49
import com.vaadin.flow.router.RouteParameters;
50
import com.vaadin.flow.router.QueryParameters;
51

52
// Error handling
53
import com.vaadin.flow.router.HasErrorParameter;
54
import com.vaadin.flow.router.ErrorParameter;
55
import com.vaadin.flow.router.RouteNotFoundError;
56
import com.vaadin.flow.router.InternalServerError;
57
import com.vaadin.flow.server.NotFoundException;
58

59
// Menu system
60
import com.vaadin.flow.router.MenuConfiguration;
61
import com.vaadin.flow.router.MenuEntry;
62

63
// Security integration
64
import com.vaadin.flow.server.auth.AnonymousAllowed;
65
import com.vaadin.flow.server.auth.PermitAll;
66
import com.vaadin.flow.server.auth.DenyAll;
67
import com.vaadin.flow.server.auth.RolesAllowed;
68

69
// Navigation highlight
70
import com.vaadin.flow.router.HighlightCondition;
71
import com.vaadin.flow.router.HighlightAction;
72

73
// Core components and UI
74
import com.vaadin.flow.component.Component;
75
import com.vaadin.flow.component.UI;
76
import com.vaadin.flow.component.HasText;
77
import com.vaadin.flow.component.HasEnabled;
78
import com.vaadin.flow.component.HtmlComponent;
79

80
// Standard Java types
81
import java.util.Optional;
82
import java.util.List;
83
import java.util.Set;
84
import java.util.Map;
85
import java.util.EventObject;
86
```
87

88
## Route Definition
89

90
### @Route Annotation
91

92
Primary annotation for defining navigation routes to views.
93

94
```java { .api }
95
@Target(ElementType.TYPE)
96
@Retention(RetentionPolicy.RUNTIME)
97
public @interface Route {
98
    String value() default "";
99
    Class<? extends RouterLayout> layout() default RouterLayout.class;
100
    boolean registerAtStartup() default true;
101
    boolean absolute() default false;
102
}
103
```
104

105
### @PageTitle Annotation
106

107
Sets the browser page title for the route.
108

109
```java { .api }
110
@Target(ElementType.TYPE)
111
@Retention(RetentionPolicy.RUNTIME)
112
public @interface PageTitle {
113
    String value();
114
}
115
```
116

117
### @Menu Annotation
118

119
Integrates the route with Vaadin's menu system.
120

121
```java { .api }
122
@Target(ElementType.TYPE)
123
@Retention(RetentionPolicy.RUNTIME)
124
public @interface Menu {
125
    String title() default "";
126
    double order() default 0.0;
127
    String icon() default "";
128
}
129
```
130

131
## Basic Navigation
132

133
### RouterLink
134

135
Component for creating navigation links between views.
136

137
```java { .api }
138
public class RouterLink extends Component implements HasText, HasEnabled {
139
    public RouterLink();
140
    public RouterLink(String text, Class<? extends Component> navigationTarget);
141
    public RouterLink(String text, Class<? extends Component> navigationTarget, Object parameter);
142

143
    // Navigation target
144
    public void setRoute(Class<? extends Component> route);
145
    public void setRoute(Class<? extends Component> route, Object parameter);
146
    public void setRoute(Class<? extends Component> route, List<Object> parameters);
147

148
    // Appearance
149
    public void setText(String text);
150
    public String getText();
151
    public void setTabIndex(int tabIndex);
152

153
    // Highlight
154
    public void setHighlightCondition(HighlightCondition<RouterLink> highlightCondition);
155
    public void setHighlightAction(HighlightAction<RouterLink> highlightAction);
156
}
157
```
158

159
### Anchor
160

161
HTML anchor component for external links and downloads.
162

163
```java { .api }
164
public class Anchor extends HtmlComponent implements HasText, HasEnabled {
165
    public Anchor();
166
    public Anchor(String href);
167
    public Anchor(String href, String text);
168

169
    public void setHref(String href);
170
    public String getHref();
171
    public void setTarget(String target);
172
    public String getTarget();
173
    public void setText(String text);
174
    public String getText();
175
}
176
```
177

178
## Parameterized Routes
179

180
### HasUrlParameter Interface
181

182
Interface for views that accept URL parameters.
183

184
```java { .api }
185
public interface HasUrlParameter<T> {
186
    void setParameter(BeforeEvent event, T parameter);
187
    void setParameter(BeforeEvent event, @OptionalParameter T parameter);
188
    void setParameter(BeforeEvent event, @WildcardParameter String parameter);
189
}
190
```
191

192
### Route Parameters
193

194
Support for various parameter types in URLs.
195

196
```java { .api }
197
// Optional parameter annotation
198
@Target(ElementType.PARAMETER)
199
@Retention(RetentionPolicy.RUNTIME)
200
public @interface OptionalParameter {
201
}
202

203
// Wildcard parameter annotation
204
@Target(ElementType.PARAMETER)
205
@Retention(RetentionPolicy.RUNTIME)
206
public @interface WildcardParameter {
207
}
208
```
209

210
## Navigation Lifecycle
211

212
### Navigation Event Interfaces
213

214
Interfaces for handling navigation lifecycle events.
215

216
```java { .api }
217
public interface BeforeEnterObserver {
218
    void beforeEnter(BeforeEnterEvent event);
219
}
220

221
public interface BeforeLeaveObserver {
222
    void beforeLeave(BeforeLeaveEvent event);
223
}
224

225
public interface AfterNavigationObserver {
226
    void afterNavigation(AfterNavigationEvent event);
227
}
228
```
229

230
### Navigation Events
231

232
Event classes providing navigation context and control.
233

234
```java { .api }
235
public class BeforeEnterEvent extends EventObject {
236
    public Location getLocation();
237
    public NavigationTrigger getTrigger();
238
    public UI getUI();
239

240
    // Navigation control
241
    public void forwardTo(String route);
242
    public void forwardTo(Class<? extends Component> routeTarget);
243
    public void rerouteTo(String route);
244
    public void rerouteTo(Class<? extends Component> routeTarget);
245

246
    // Parameter access
247
    public RouteParameters getRouteParameters();
248
    public QueryParameters getQueryParameters();
249

250
    // Error handling
251
    public boolean hasErrorParameter();
252
    public ErrorParameter<?> getErrorParameter();
253
}
254

255
public class BeforeLeaveEvent extends EventObject {
256
    public Location getLocation();
257
    public NavigationTrigger getTrigger();
258
    public UI getUI();
259

260
    // Navigation control
261
    public void postpone();
262
    public ContinueNavigationAction getContinueNavigationAction();
263
}
264

265
public class AfterNavigationEvent extends EventObject {
266
    public Location getLocation();
267
    public LocationChangeEvent getLocationChangeEvent();
268
    public List<Component> getActiveChain();
269
}
270
```
271

272
### Navigation Trigger
273

274
Enum indicating how navigation was triggered.
275

276
```java { .api }
277
public enum NavigationTrigger {
278
    USER,           // User-initiated navigation
279
    PROGRAMMATIC,   // Programmatic navigation
280
    ROUTER_LINK,    // RouterLink click
281
    HISTORY,        // Browser history navigation
282
    REFRESH         // Page refresh
283
}
284
```
285

286
## Route Layouts
287

288
### RouterLayout Interface
289

290
Interface for components that serve as layout containers for routed content.
291

292
```java { .api }
293
public interface RouterLayout extends Component {
294
    void showRouterLayoutContent(HasElement content);
295

296
    // Optional lifecycle methods
297
    default void afterNavigation(AfterNavigationEvent event) {}
298
    default void beforeEnter(BeforeEnterEvent event) {}
299
    default void beforeLeave(BeforeLeaveEvent event) {}
300
}
301
```
302

303
### ParentLayout Annotation
304

305
Specifies parent layouts for nested layout structures.
306

307
```java { .api }
308
@Target(ElementType.TYPE)
309
@Retention(RetentionPolicy.RUNTIME)
310
public @interface ParentLayout {
311
    Class<? extends RouterLayout> value();
312
}
313
```
314

315
## Programmatic Navigation
316

317
### UI Navigation Methods
318

319
Methods for programmatic navigation within the current UI.
320

321
```java { .api }
322
public class UI extends Component {
323
    // Navigation
324
    public void navigate(String location);
325
    public void navigate(Class<? extends Component> navigationTarget);
326
    public void navigate(Class<? extends Component> navigationTarget, Object parameter);
327
    public void navigate(Class<? extends Component> navigationTarget, RouteParameters parameters);
328

329
    // Current location
330
    public Location getInternals().getActiveViewLocation();
331
    public Router getRouter();
332
}
333
```
334

335
### Router Class
336

337
Core routing functionality and configuration.
338

339
```java { .api }
340
public class Router {
341
    public Optional<NavigationResult> navigate(UI ui, Location location, NavigationTrigger trigger);
342
    public void reconfigure(RouteConfiguration configuration);
343
    public RouteConfiguration getConfiguration();
344

345
    // Route resolution
346
    public Optional<String> getUrl(Class<? extends Component> navigationTarget);
347
    public Optional<String> getUrl(Class<? extends Component> navigationTarget, RouteParameters parameters);
348
}
349
```
350

351
## Route Configuration
352

353
### RouteConfiguration
354

355
Configuration and registration of routes.
356

357
```java { .api }
358
public class RouteConfiguration {
359
    public static RouteConfiguration forSessionScope();
360
    public static RouteConfiguration forApplicationScope();
361

362
    // Route registration
363
    public void setRoute(String path, Class<? extends Component> navigationTarget);
364
    public void setRoute(String path, Class<? extends Component> navigationTarget,
365
                        Class<? extends RouterLayout> parentLayout);
366
    public void removeRoute(String path);
367
    public void removeRoute(Class<? extends Component> navigationTarget);
368

369
    // Route information
370
    public List<RouteData> getAvailableRoutes();
371
    public Optional<Class<? extends Component>> getRoute(String path);
372
    public Optional<String> getTemplate(Class<? extends Component> navigationTarget);
373

374
    // Parent chain
375
    public List<Class<? extends RouterLayout>> getParentLayouts(Class<? extends Component> navigationTarget);
376
}
377
```
378

379
### RouteData
380

381
Information about registered routes.
382

383
```java { .api }
384
public class RouteData {
385
    public String getUrl();
386
    public List<Class<?>> getParameterTypes();
387
    public Class<? extends Component> getNavigationTarget();
388
    public List<Class<? extends RouterLayout>> getParentLayouts();
389
    public String getTemplate();
390
}
391
```
392

393
## Route Parameters and Query Parameters
394

395
### RouteParameters
396

397
Container for route path parameters.
398

399
```java { .api }
400
public class RouteParameters {
401
    public static RouteParameters empty();
402
    public static RouteParameters of(String name, String value);
403
    public static RouteParameters of(String name1, String value1, String name2, String value2);
404

405
    public Optional<String> get(String name);
406
    public String getOrDefault(String name, String defaultValue);
407
    public Set<String> getParameterNames();
408
    public Map<String, String> getParameters();
409

410
    public RouteParameters and(String name, String value);
411
    public RouteParameters and(RouteParameters other);
412
}
413
```
414

415
### QueryParameters
416

417
Container for URL query parameters.
418

419
```java { .api }
420
public class QueryParameters {
421
    public static QueryParameters empty();
422
    public static QueryParameters simple(Map<String, String> parameters);
423
    public static QueryParameters full(Map<String, List<String>> parameters);
424

425
    public Optional<String> getSingleParameter(String name);
426
    public List<String> getParameters(String name);
427
    public Set<String> getParameterNames();
428
    public Map<String, List<String>> getParameters();
429

430
    public String getQueryString();
431
}
432
```
433

434
### Location
435

436
Represents a navigation location with path and query parameters.
437

438
```java { .api }
439
public class Location {
440
    public Location(String path);
441
    public Location(String path, QueryParameters queryParameters);
442

443
    public String getPath();
444
    public List<String> getSegments();
445
    public String getPathWithQueryParameters();
446
    public QueryParameters getQueryParameters();
447

448
    public Location toggleTrailingSlash();
449
    public Location appendSegment(String segment);
450
    public Location appendPath(String path);
451
}
452
```
453

454
## Error Handling
455

456
### Error Routes
457

458
Special routes for handling navigation errors.
459

460
```java { .api }
461
@Target(ElementType.TYPE)
462
@Retention(RetentionPolicy.RUNTIME)
463
public @interface ErrorRoute {
464
    Class<? extends RouterLayout> layout() default RouterLayout.class;
465
}
466
```
467

468
### HasErrorParameter Interface
469

470
Interface for error handling views.
471

472
```java { .api }
473
public interface HasErrorParameter<T extends Exception> {
474
    int setErrorParameter(BeforeEnterEvent event, ErrorParameter<T> parameter);
475
}
476

477
public class ErrorParameter<T extends Exception> {
478
    public T getException();
479
    public String getCustomMessage();
480
    public boolean hasCustomMessage();
481
    public Class<T> getCaughtExceptionType();
482
}
483
```
484

485
### Standard Error Views
486

487
Built-in error handling components.
488

489
```java { .api }
490
public class RouteNotFoundError extends Component implements HasErrorParameter<NotFoundException> {
491
    public int setErrorParameter(BeforeEnterEvent event, ErrorParameter<NotFoundException> parameter);
492
}
493

494
public class InternalServerError extends Component implements HasErrorParameter<Exception> {
495
    public int setErrorParameter(BeforeEnterEvent event, ErrorParameter<Exception> parameter);
496
}
497
```
498

499
## Menu Integration
500

501
### Menu Configuration
502

503
Programmatic menu configuration and management.
504

505
```java { .api }
506
public class MenuConfiguration {
507
    public static MenuConfiguration getMenuConfiguration(UI ui);
508

509
    // Menu items
510
    public void addMenuItem(MenuEntry menuEntry);
511
    public void removeMenuItem(String path);
512
    public List<MenuEntry> getMenuEntries();
513

514
    // Menu structure
515
    public void setMenuOrder(List<String> menuOrder);
516
    public List<String> getMenuOrder();
517
}
518

519
public class MenuEntry {
520
    public MenuEntry(String path, String title);
521
    public MenuEntry(String path, String title, double order);
522
    public MenuEntry(String path, String title, String icon);
523

524
    public String getPath();
525
    public String getTitle();
526
    public double getOrder();
527
    public String getIcon();
528
    public Class<? extends Component> getMenuClass();
529
}
530
```
531

532
## Navigation Guards
533

534
### Route Access Control
535

536
Integration with security frameworks for route protection.
537

538
```java { .api }
539
// Spring Security integration
540
@Target({ElementType.TYPE, ElementType.METHOD})
541
@Retention(RetentionPolicy.RUNTIME)
542
public @interface AnonymousAllowed {
543
}
544

545
@Target({ElementType.TYPE, ElementType.METHOD})
546
@Retention(RetentionPolicy.RUNTIME)
547
public @interface PermitAll {
548
}
549

550
@Target({ElementType.TYPE, ElementType.METHOD})
551
@Retention(RetentionPolicy.RUNTIME)
552
public @interface DenyAll {
553
}
554

555
@Target({ElementType.TYPE, ElementType.METHOD})
556
@Retention(RetentionPolicy.RUNTIME)
557
public @interface RolesAllowed {
558
    String[] value();
559
}
560
```
561

562
## Usage Examples
563

564
### Basic Route Definition
565

566
```java
567
@Route("users")
568
@PageTitle("User Management")
569
@Menu(title = "Users", order = 1.0, icon = "vaadin:users")
570
public class UserView extends VerticalLayout {
571
    public UserView() {
572
        add(new H1("User Management"));
573
        // View content
574
    }
575
}
576
```
577

578
### Parameterized Route
579

580
```java
581
@Route("user/:userID")
582
@PageTitle("User Details")
583
public class UserDetailsView extends VerticalLayout implements HasUrlParameter<String> {
584

585
    @Override
586
    public void setParameter(BeforeEvent event, String userID) {
587
        User user = userService.findById(userID);
588
        if (user == null) {
589
            event.rerouteTo(NotFoundView.class);
590
            return;
591
        }
592
        showUserDetails(user);
593
    }
594
}
595
```
596

597
### Navigation Guards
598

599
```java
600
@Route("admin")
601
@RolesAllowed("ADMIN")
602
public class AdminView extends VerticalLayout implements BeforeEnterObserver {
603

604
    @Override
605
    public void beforeEnter(BeforeEnterEvent event) {
606
        if (!hasAdminAccess()) {
607
            event.rerouteTo(AccessDeniedView.class);
608
        }
609
    }
610
}
611
```
612

613
### Nested Layouts
614

615
```java
616
@Route(value = "main", layout = MainLayout.class)
617
public class MainView extends VerticalLayout {
618
    // View implementation
619
}
620

621
@ParentLayout(AppLayout.class)
622
public class MainLayout extends VerticalLayout implements RouterLayout {
623
    @Override
624
    public void showRouterLayoutContent(HasElement content) {
625
        getElement().appendChild(content.getElement());
626
    }
627
}
628
```
629

630
### Programmatic Navigation
631

632
```java
633
public void navigateToUser(String userId) {
634
    UI.getCurrent().navigate("user/" + userId);
635

636
    // Or with type safety
637
    UI.getCurrent().navigate(UserDetailsView.class, userId);
638

639
    // With route parameters
640
    RouteParameters params = new RouteParameters("userID", userId);
641
    UI.getCurrent().navigate(UserDetailsView.class, params);
642
}
643
```
644

645
The routing system provides comprehensive navigation capabilities for building complex single-page applications with proper URL management, browser history support, and deep linking.