> For the complete documentation index, see [llms.txt](https://docs.aurelia.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aurelia.io/getting-to-know-aurelia/aurelia-router.md).

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

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

## 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](/aurelia-packages/store.md) 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.