# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.