# Routing

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](https://github.com/aurelia/aurelia/blob/master/docs/user-docs/getting-to-know-aurelia/routing/choosing-a-router.md).

## 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`](https://github.com/aurelia/aurelia/blob/master/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](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/fundamentals/getting-started)
   * [Router configuration](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/fundamentals/router-configuration)
   * [Defining routes and viewports](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/fundamentals/configuring-routes) · [Viewports in depth](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/fundamentals/viewports)
2. **Navigation patterns**
   * [Imperative navigation](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/navigation/navigating)
   * [Build menus with the navigation model](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/navigation/navigation-model)
   * [Accessing the active route](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/navigation/current-route)
3. **Lifecycle, hooks, and events**
   * [Routing lifecycle](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/lifecycle-and-events/routing-lifecycle)
   * [Router hooks](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/lifecycle-and-events/router-hooks)
   * [Router events](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/lifecycle-and-events/router-events)
4. **Advanced scenarios**
   * [Transition plans](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/advanced/transition-plans)
   * [Router state management](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/advanced/router-state-management)
   * [Error handling](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/advanced/error-handling)
   * [Advanced API reference](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/advanced/advanced-api-reference)
5. **Support resources**
   * [Testing guide](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/support/testing-guide)
   * [Troubleshooting](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/support/troubleshooting)

Keep the [live StackBlitz examples](https://stackblitz.com/@Sayan751/collections/router-lite) 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](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/fundamentals/router-configuration)   |
| Map URLs to components with strong typing              | `@route` decorator inside your component                         | [Defining routes](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/fundamentals/configuring-routes)          |
| Compose multiple viewports or named layouts            | `<au-viewport>` and named viewports                              | [Viewports](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/fundamentals/viewports)                         |
| Control navigation flow                                | Lifecycle hooks (`canLoad`, `loading`, `canUnload`, `unloading`) | [Routing lifecycle](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/lifecycle-and-events/routing-lifecycle) |
| Listen for navigation changes                          | `Router.addEventListener(...)` or DI inject `IRouterEvents`      | [Router events](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/lifecycle-and-events/router-events)         |
| Persist and observe route state                        | Inject `ICurrentRoute` / `IRouter`                               | [Router state management](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/advanced/router-state-management) |
| Customize transitions                                  | Provide a `transitionPlan` or set per-route strategies           | [Transition plans](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router/advanced/transition-plans)               |

## Where to go next

* Explore targeted recipes in the [developer guides](https://github.com/aurelia/aurelia/blob/master/docs/user-docs/developer-guides/routing/configured-routing.md).
* Pair routing with state management via [the store plugin](https://docs.aurelia.io/aurelia-packages/store) or your preferred data layer.
* Review the [router package CHANGELOG](https://github.com/aurelia/aurelia/blob/master/packages/router/CHANGELOG.md) when upgrading between versions.