Navigation model

Create a navigation menu using navigation model in Router.

The navigation model can be thought of as view-friendly version of the configured routes. It provides similar information as of the configured routes with some additional data to it. This is typically useful when you want to create navigation menu from the already registered/configured routes in the router, without necessarily duplicating the data. The information takes the following shape.

interface INavigationModel {
  /**
   * Collection of routes.
   */
  readonly routes: readonly INavigationRoute[];

  /**
   * Wait for async route configurations.
   */
  resolve(): Promise<void> | void;
}

interface INavigationRoute {
  readonly id: string | null;
  readonly path: string[];
  readonly title: string | ((node: RouteNode) => string | null) | null;
  readonly data: Record<string, unknown>;
  readonly isActive: boolean;
}

The navigation model contains a view-friendly subset of each route's configuration (id, path, title, and data) plus an isActive flag. Redirect-only routes are excluded.

This section provides example of how to use navigation model while discussing different aspects of it.

Create a navigation menu using a navigation model

The following example shows how to create a navigation menu using the info from the navigation model.

router-lite - navigation-model - StackBlitzStackBlitz

In this example, we are using a custom element named nav-bar. In the custom element we inject an instance of IRouteContext and we grab the navigation model from the routing context.

import { resolve } from '@aurelia/kernel';
import { INavigationModel, IRouteContext } from '@aurelia/router';

export class NavBar {
  private readonly navModel: INavigationModel = resolve(IRouteContext).routeConfigContext.navigationModel;

  public async binding() {
    await this.navModel.resolve()
  }
}

Then the information from the model is used in the view to create the navigation menu.

<nav style="display: flex; gap: 0.5rem;">
    <template repeat.for="route of navModel.routes">
        <a href.bind="route.path | firstNonEmpty">\${route.title}</a>
    </template>
</nav>

It additionally shows that from the NavBar#binding, INavigationModel#resolve() is awaited. This is recommended, when dealing with async route configuration. This allows all the promises to be resolved and thereafter building the navigation information correctly.

Note that in the example above we aren't dealing with async routing. Therefore, for that example waiting the INavigationModel#resolve() can be avoided.

In case you want to inject the IRouteContext in the app-root, you need to use a lazy injection, for example: routeContext = resolve(lazy(IRouteContext)). An eager injection does not work for app-root due to the timing of app root and the root route-context creation.

Using the isActive property

The isActive property is true when this route is currently active (loaded), and otherwise it is false. A typical use-case for this property is to apply or remove the "active" style to the links, depending on if the link is active or not. You can see this in the following example where a new .active class is added and that is bound to the isActive property.

<style>
  .active {
    font-weight: bold;
  }
</style>
<nav>
  <template repeat.for="route of navModel.routes">
    <a href.bind="route.path | firstNonEmpty" active.class="route.isActive">${route.title}</a>
  </template>
</nav>

You can see this in action below.

router-lite - navigation-model - isactive - StackBlitzStackBlitz

Excluding routes from the navigation model

By default, all configured routes are added to the navigation model. However, there might be routes which is desired to be excluded from the navigation model; for example: a fallback route for un-configured routes. To this end, a route can be configured with nav: false to instruct the router not to included it in the navigation model.

import { route } from '@aurelia/router';
import { Home } from './home';
import { About } from './about';
import { NotFound } from './not-found';

@route({
  routes: [
    {
      path: ['', 'home'],
      component: Home,
      title: 'Home',
    },
    {
      path: 'about',
      component: About,
      title: 'About',
    },
    {
      path: 'notfound',
      component: NotFound,
      title: 'Not found',
      nav: false,       // <-- exclude from navigation model
    },
  ],
  fallback: 'notfound',
})
export class MyApp {}

You see this in action in the example below.

router-lite - navigation-model - exclusion - StackBlitzStackBlitz

Disabling navigation model

If you are not creating a menu using the navigation model, you can also deactivate the navigation model by setting false to the useNavigationModel router option. Doing so, will set the IRouteConfigContext#navigationModel to null and skip further processing.

Combining ICurrentRoute with the navigation model

While the navigation model provides information about all configured routes, sometimes you also need the exact active route or query parameters. The ICurrentRoute object can be injected in tandem with your navigation model:

import { IRouteContext, INavigationModel, ICurrentRoute } from '@aurelia/router';
import { resolve } from '@aurelia/kernel';

export class NavBar {
  // same as regular usage of navigation model
  private readonly navModel: INavigationModel = resolve(IRouteContext).routeConfigContext.navigationModel;
  private readonly currentRoute = resolve(ICurrentRoute);

  public async binding() {
    await this.navModel.resolve();
    console.log('Active segment:', this.currentRoute.path);
    console.log('Active query:', this.currentRoute.url.split('?')[1]);
  }
}

Using both navModel and currentRoute, you can dynamically highlight the active route in your navigation menu, differentiate query-only changes, and so on.