Routing

Understand the @aurelia/router package, its core concepts, and how to navigate the rest of the routing documentation.

Aurelia's primary router gives you a declarative, component-first navigation system with strong type safety, multi-viewport layouts, and deep integration with dependency injection. If you have used Angular's router or the classic Aurelia 1 router, the mental model will feel familiar: define a route table, map URLs to components, nest layouts, guard navigation, lazy-load feature areas, and respond to lifecycle events. The Aurelia router stays HTML-friendly and convention-driven, letting you compose navigation without wrapper modules or excessive configuration.

Still deciding between routers? Start with Choosing the right Aurelia router.

Highlights

• Structured route tree lets you describe nested layouts, auxiliary viewports, and fallback routes in one place while still co-locating child routes with their components via @route.

• Viewport-first layouts allow flexible page composition: declare multiple <au-viewport> elements, name them, and target them from route definitions. This makes responsive shells and split views straightforward.

• Lifecycle hooks and events mirror the intent of Angular guards (canLoad, canActivate, etc.) while using Aurelia conventions (canLoad, loading, canUnload, unloading). Hooks execute in well-defined order and support async work.

• Navigation state management gives you centralized insight into route activation, title building, and analytics hooks, ideal for larger apps.

• Progressive enhancement via the load and href attributes keeps markup readable and usable even before hydration.

Refer to the package README for release notes and API exports: packages/router/README.md.

Choose the right guide

Work through the topics in this order when you are new to the router:

1. Fundamentals

   • Getting started

   • Router configuration

   • Defining routes and viewports · Viewports in depth

2. Navigation patterns

   • Imperative navigation

   • Build menus with the navigation model

   • Accessing the active route

3. Lifecycle, hooks, and events

   • Routing lifecycle

   • Router hooks

   • Router events

4. Advanced scenarios

   • Transition plans

   • Router state management

   • Error handling

   • Advanced API reference

5. Support resources

   • Testing guide

   • Troubleshooting

Keep the live StackBlitz examples handy while you read; most topics embed a runnable demo.

Feature map

Capability	How to use it	Related doc
Configure base path, hash vs pushState, title building	RouterConfiguration.customize and RouterOptions	Router configuration
Map URLs to components with strong typing	@route decorator inside your component	Defining routes
Compose multiple viewports or named layouts	<au-viewport> and named viewports	Viewports
Control navigation flow	Lifecycle hooks (canLoad, loading, canUnload, unloading)	Routing lifecycle
Listen for navigation changes	Router.addEventListener(...) or DI inject IRouterEvents	Router events
Persist and observe route state	Inject ICurrentRoute / IRouter	Router state management
Customize transitions	Provide a transitionPlan or set per-route strategies	Transition plans

Where to go next

• Explore targeted recipes in the developer guides.

• Pair routing with state management via the store plugin or your preferred data layer.

• Review the router package CHANGELOG when upgrading between versions.