LogoLogo
HomeDiscourseBlogDiscord
  • Introduction
  • Introduction
    • Quick start
    • Aurelia for new developers
    • Hello world
      • Creating your first app
      • Your first component - part 1: the view model
      • Your first component - part 2: the view
      • Running our app
      • Next steps
  • Templates
    • Template Syntax
      • Attribute binding
      • Event binding
      • Text interpolation
      • Template promises
      • Template references
      • Template variables
      • Globals
    • Custom attributes
    • Value converters (pipes)
    • Binding behaviors
    • Form Inputs
    • CSS classes and styling
    • Conditional Rendering
    • List Rendering
    • Lambda Expressions
    • Local templates (inline templates)
    • SVG
  • Components
    • Component basics
    • Component lifecycles
    • Bindable properties
    • Styling components
    • Slotted content
    • Scope and context
    • CustomElement API
    • Template compilation
      • processContent
      • Extending templating syntax
      • Modifying template parsing with AttributePattern
      • Extending binding language
      • Using the template compiler
      • Attribute mapping
  • Getting to know Aurelia
    • Routing
      • @aurelia/router
        • Getting Started
        • Creating Routes
        • Routing Lifecycle
        • Viewports
        • Navigating
        • Route hooks
        • Router animation
        • Route Events
        • Router Tutorial
        • Router Recipes
      • @aurelia/router-lite
        • Getting started
        • Router configuration
        • Configuring routes
        • Viewports
        • Navigating
        • Lifecycle hooks
        • Router hooks
        • Router events
        • Navigation model
        • Transition plan
    • App configuration and startup
    • Enhance
    • Template controllers
    • Understanding synchronous binding
    • Dynamic composition
    • Portalling elements
    • Observation
      • Observing property changes with @observable
      • Effect observation
      • HTML observation
      • Using observerLocator
    • Watching data
    • Dependency injection (DI)
    • App Tasks
    • Task Queue
    • Event Aggregator
  • Developer Guides
    • Animation
    • Testing
      • Overview
      • Testing attributes
      • Testing components
      • Testing value converters
      • Working with the fluent API
      • Stubs, mocks & spies
    • Logging
    • Building plugins
    • Web Components
    • UI virtualization
    • Errors
      • 0001 to 0023
      • 0088 to 0723
      • 0901 to 0908
    • Bundlers
    • Recipes
      • Apollo GraphQL integration
      • Auth0 integration
      • Containerizing Aurelia apps with Docker
      • Cordova/Phonegap integration
      • CSS-in-JS with Emotion
      • DOM style injection
      • Firebase integration
      • Markdown integration
      • Multi root
      • Progress Web Apps (PWA's)
      • Securing an app
      • SignalR integration
      • Strongly-typed templates
      • TailwindCSS integration
      • WebSockets Integration
      • Web Workers Integration
    • Playground
      • Binding & Templating
      • Custom Attributes
        • Binding to Element Size
      • Integration
        • Microsoft FAST
        • Ionic
    • Migrating to Aurelia 2
      • For plugin authors
      • Side-by-side comparison
    • Cheat Sheet
  • Aurelia Packages
    • Validation
      • Validation Tutorial
      • Plugin Configuration
      • Defining & Customizing Rules
      • Architecture
      • Tagging Rules
      • Model Based Validation
      • Validation Controller
      • Validate Binding Behavior
      • Displaying Errors
      • I18n Internationalization
      • Migration Guide & Breaking Changes
    • i18n Internationalization
    • Fetch Client
      • Overview
      • Setup and Configuration
      • Response types
      • Working with forms
      • Intercepting responses & requests
      • Advanced
    • Event Aggregator
    • State
    • Store
      • Configuration and Setup
      • Middleware
    • Dialog
  • Tutorials
    • Building a ChatGPT inspired app
    • Building a realtime cryptocurrency price tracker
    • Building a todo application
    • Building a weather application
    • Building a widget-based dashboard
    • React inside Aurelia
    • Svelte inside Aurelia
    • Synthetic view
    • Vue inside Aurelia
  • Community Contribution
    • Joining the community
    • Code of conduct
    • Contributor guide
    • Building and testing aurelia
    • Writing documentation
    • Translating documentation
Powered by GitBook
On this page
  • Using the href custom attribute
  • Using route-id
  • Targeting viewports
  • Navigate in current and ancestor routing context
  • Bypassing the href custom attribute
  • Using the load custom attribute
  • Binding the route-params
  • Using the route view-model class as route
  • Customize the routing context
  • active status
  • "active" CSS class
  • Using the Router API
  • Using string instructions
  • Using non-string routing instructions
  • Using navigation options
  • Redirection and unknown paths
  • Checking or using the current route while navigating

Was this helpful?

Export as PDF
  1. Getting to know Aurelia
  2. Routing
  3. @aurelia/router-lite

Navigating

Learn to navigate from one view to another using the Router-Lite. Also learn about routing context.

PreviousViewportsNextLifecycle hooks

Last updated 2 months ago

Was this helpful?

This section details the various ways that you can use to navigate from one part of your application to another part. For performing navigation the router-lite offers couple of alternatives, namely the href and the load custom attributes, and the IRouter#load method.

Using the href custom attribute

You can use the href custom attribute with an a (anchor) tag, with a string value. When the users click this link, the router-lite performs the navigation. This can be seen in action in the live example below.

The example shows that there are two configured routes, home and about, and in markup there are two anchor tags that points to these routes. Clicking those links the users can navigate to the desired components, as it is expected.

<nav>
  <a href="home">Home</a>
  <a href="about">About</a>
</nav>
import { route } from '@aurelia/router-lite';
import { Home } from './home';
import { About } from './about';

@route({
  routes: [
    {
      path: ['', 'home'],
      component: Home,
    },
    {
      path: 'about',
      component: About,
    },
  ],
})
export class MyApp {}

You can also use the parameterized routes with the href attribute, exactly the same way. To this end, you need to put the parameter value in the path itself and use the parameterized path in the href attribute. This is shown in the example below.

The example shows two configured routes; one with an optional parameter. The markup has three anchor tags as follows:

<nav>
  <a href="home">Home</a>
  <a href="about">About</a>
  <a href="about/42">About/42</a>
</nav>
import { route } from '@aurelia/router-lite';
import { Home } from './home';
import { About } from './about';

@route({
  routes: [
    {
      path: ['', 'home'],
      component: Home,
    },
    {
      path: ['about/:id?'],
      component: About,
    },
  ],
})
export class MyApp {}

The last href attribute is an example of a parameterized route.

Using route-id

Note that the example set a route id that is different than the defined path. These route-ids are later used in the markup as the values for the href attributes.

import { route } from '@aurelia/router-lite';
import { ChildOne } from './child1';
import { ChildTwo } from './child2';

@route({
  routes: [
    {
      id: 'r1',
      path: ['', 'c1'],
      component: ChildOne,
    },
    {
      id: 'r2',
      path: 'c2',
      component: ChildTwo,
    },
  ],
})
export class MyApp {}
<nav>
  <a href="r1">C1</a>
  <a href="r2">C2</a>
</nav>
import { route } from '@aurelia/router-lite';
import { customElement } from '@aurelia/runtime-html';

@customElement({ name: 'gc-11', template: 'gc11' })
class GrandChildOneOne {}

@customElement({ name: 'gc-12', template: 'gc12' })
class GrandChildOneTwo {}

@route({
  routes: [
    { id: 'r1', path: ['', 'gc11'], component: GrandChildOneOne },
    { id: 'r2', path: 'gc12', component: GrandChildOneTwo },
  ],
})
@customElement({
  name: 'c-one',
  template: `c1 <br>
  <nav>
    <a href="r1">gc11</a>
    <a href="r2">gc12</a>
  </nav>
  <br>
  <au-viewport></au-viewport>`,
})
export class ChildOne {}
import { route } from '@aurelia/router-lite';
import { customElement } from '@aurelia/runtime-html';

@customElement({ name: 'gc-21', template: 'gc21' })
class GrandChildTwoOne {}

@customElement({ name: 'gc-22', template: 'gc22' })
class GrandChildTwoTwo {}

@route({
  routes: [
    { id: 'r1', path: ['', 'gc21'], component: GrandChildTwoOne },
    { id: 'r2', path: 'gc22', component: GrandChildTwoTwo },
  ],
})
@customElement({
  name: 'c-two',
  template: `c2 <br>
  <nav>
    <a href="r1">gc21</a>
    <a href="r2">gc22</a>
    <a href="c1">c1 (doesn't work)</a>
    <a href="../c1">../c1 (works)</a>
  </nav>
  <br>
  <au-viewport></au-viewport>`,
})
export class ChildTwo {}

Targeting viewports

{path1}[@{viewport-name}][+{path2}[@{sibling-viewport-name}]]

The following live example, demonstrates that.

The example shows the following variations.

<!-- Load the products' list in the first viewport and the details in the second viewport -->
<a href="products+details/${id}">Load products+details/${id}</a>

<!-- Load the details in the first viewport and the products' list in the second viewport -->
<a href="details/${id}+products">Load details/${id}+products</a>

<!-- Specifically target the named viewports -->
<a href="products@list+details/${id}@details">Load products@list+details/${id}@details</a>
<a href="products@details+details/${id}@list">Load products@details+details/${id}@list</a>

<!-- Load only the details in the specific named viewport -->
<a href="details/${id}@details">Load details/${id}@details</a>

Note that using the viewport name in the routing instruction is optional and when omitted, the router uses the first available viewport.

Navigate in current and ancestor routing context

The navigation using href attribute always happens in the current routing context; that is, the routing instruction will be successful if and only the route is configured in the current routing parent. This is shown in the example below.

import { route } from '@aurelia/router-lite';
import { ChildOne } from './child1';
import { ChildTwo } from './child2';
import { NotFound } from './not-found';

@route({
  routes: [
    {
      path: ['', 'c1'],
      component: ChildOne,
    },
    {
      path: 'c2',
      component: ChildTwo,
    },
    {
      path: 'not-found',
      component: NotFound,
    },
  ],
  fallback: 'not-found',
})
@customElement({ name: 'my-app', template })
export class MyApp {}
import { route } from '@aurelia/router-lite';
import { customElement } from '@aurelia/runtime-html';

@customElement({ name: 'gc-11', template: 'gc11' })
class GrandChildOneOne {}

@customElement({ name: 'gc-12', template: 'gc12' })
class GrandChildOneTwo {}

@route({
  routes: [
    { id: 'r1', path: ['', 'gc11'], component: GrandChildOneOne },
    { id: 'r2', path: 'gc12', component: GrandChildOneTwo },
  ],
})
@customElement({
  name: 'c-one',
  template: `c1 <br>
  <nav>
    <a href="r1">gc11</a>
    <a href="r2">gc12</a>
    <a href="c2">c2 (doesn't work)</a>
    <a href="../c2">../c2 (works)</a>
  </nav>
  <br>
  <au-viewport></au-viewport>`,
})
export class ChildOne {}
import { route } from '@aurelia/router-lite';
import { customElement } from '@aurelia/runtime-html';

@customElement({ name: 'gc-21', template: 'gc21' })
class GrandChildTwoOne {}

@customElement({ name: 'gc-22', template: 'gc22' })
class GrandChildTwoTwo {}

@route({
  routes: [
    { id: 'r1', path: ['', 'gc21'], component: GrandChildTwoOne },
    { id: 'r2', path: 'gc22', component: GrandChildTwoTwo },
  ],
})
@customElement({
  name: 'c-two',
  template: `c2 <br>
  <nav>
    <a href="r1">gc21</a>
    <a href="r2">gc22</a>
    <a href="c1">c1 (doesn't work)</a>
    <a href="../c1">../c1 (works)</a>
  </nav>
  <br>
  <au-viewport></au-viewport>`,
})
export class ChildTwo {}

In the example, the root component has two child-routes (c1, c2) and every child component in turn has 2 child-routes (gc11, and gc12 and gc21, and gc22 respectively) of their own. In this case, any href pointing to any of the immediate child-routes (and thus configured in the current routing parent) works as expected. However, when an href, like below (refer child1.ts), is used to navigate from one child component to another child component, it does not work.

 <a href="c2">c2 (doesn't work)</a>

In such cases, the router-lite offers the following syntax to make such navigation possible.

<a href="../c2">../c2 (works)</a>

That is, you can use ../ prefix to instruct the router to point to the parent routing context. The prefix can also be used multiple times to point to any ancestor routing context. Naturally, this does not go beyond the root routing context.

Bypassing the href custom attribute

To disable/bypass the default handling of router-lite for any particular href attribute, you can avail couple of different ways as per your need and convenience.

  • Using external or data-external attribute on the a tag.

  • Using a non-null value for the target, other than the current window name, or _self.

Other than that, when clicking the link if either of the alt, ctrl, shift, meta key is pressed, the router-lite ignores the routing instruction and the default handling of clicking a link takes place.

Following example demonstrate these options.

Using the load custom attribute

To support structured way to constructing URL the router-lite offers another alternative namely the load attribute. This custom attribute accepts structured routing instructions as well as string-instructions, just like the href attribute. Before starting the discussion on the features supported exclusively by the load attribute, let us quickly review the following example of using string-instructions with the load attribute.

The example shows various instances of load attribute with various string instructions.

<!-- my-app.html -->
<!-- instructions pointing to individual routes -->
<a load="c1">C1</a>
<a load="c2">C2</a>
<!-- instructions involving sibling viewports -->
<a load="c1+c2">C1+C2</a>
<a load="c1@vp2+c2@vp1">C1@vp2+C2@vp1</a>

<!-- child1 -->
<!-- instruction pointing to parent routing context -->
<a load="../c2">../c2</a>

The following sections discuss the various other ways routing instruction can be used with the load attribute.

Binding the route-params

Using the bindable params property in the load custom attribute, you can bind the parameters for a parameterized route. The complete URL is then constructed from the given route and the parameters. Following is an example where the route-id is used with bound parameters.

The example above configures a route as follows. The route-id is then used in the markup with the bound params, as shown in the example below.

import { route } from '@aurelia/router-lite';
import { ChildTwo } from './child2';

@route({
  routes: [
    {
      id: 'r2',
      path: ['c2/:p1/foo/:p2?', 'c2/:p1/foo/:p2/bar/:p3'],
      component: ChildTwo,
    },
  ],
})
export class MyApp {}
<!-- constructed path: /c2/1/foo/ -->
<a load="route: r2; params.bind: {p1: 1};">C2 {p1: 1}</a>

<!-- constructed path: /c2/2/foo/3 -->
<a load="route: r2; params.bind: {p1: 2, p2: 3};">C2 {p1: 2, p2: 3}</a>

<!-- constructed path: /c2/4/foo/?p3=5 -->
<a load="route: r2; params.bind: {p1: 4, p3: 5};">C2 {p1: 4, p3: 5}</a>

<!-- constructed path: /c2/6/foo/7/bar/8 -->
<a load="route: r2; params.bind: {p1: 6, p2: 7, p3: 8};">C2 {p1: 6, p2: 7, p3: 8}</a>

<!-- constructed path: /c2/9/foo/10/bar/11?p4=awesome&p5=possum -->
<a load="route: r2; params.bind: {p1: 9, p2: 10, p3: 11, p4: 'awesome', p5: 'possum'};">C2 {p1: 9, p2: 10, p3: 11, p4: 'awesome', p5: 'possum'}</a>

An important thing to note here is how the URL paths are constructed for each URL. Based on the given set of parameters, a path is selected from the configured set of paths for the route, that maximizes the number of matched parameters at the same time meeting the parameter constraints.

For example, the third instance (params: {p1: 4, p3: 5}) creates the path /c2/4/foo/?p3=5 (instance of 'c2/:p1/foo/:p2?' path) even though there is a path with :p3 configured. This happens because the bound parameters-object is missing the p2 required parameter in the path pattern 'c2/:p1/foo/:p2/bar/:p3'. Therefore, it constructs the path using the pattern 'c2/:p1/foo/:p2?' instead.

In other case, the fourth instance provides a value for p2 as well as a value for p3 that results in the construction of path /c2/6/foo/7/bar/8 (instance of 'c2/:p1/foo/:p2/bar/:p3'). This case also demonstrates the aspect of "maximization of parameter matching" while path construction.

One last point to note here is that when un-configured parameters are included in the params object, those are converted into query string.

Using the route view-model class as route

// my-app.ts
import { ChildOne } from './child1';
import { ChildTwo } from './child2';

export class MyApp {
  private readonly child1: typeof ChildOne = ChildOne;
  private readonly child2: typeof ChildTwo = ChildTwo;
}
<!-- my-app.html -->
<a load="route.bind: child1">C1</a>
<a load="route.bind: child2; params.bind: {p1: 1};">C2 {p1: 1}</a>
<a load="route.bind: child2; params.bind: {p1: 2, p2: 3};">C2 {p1: 2, p2: 3}</a>
<a load="route.bind: child2; params.bind: {p1: 4, p3: 5};">C2 {p1: 4, p3: 5}</a>
<a load="route.bind: child2; params.bind: {p1: 6, p2: 7, p3: 8};">C2 {p1: 6, p2: 7, p3: 8}</a>
<a load="route.bind: child2; params.bind: {p1: 9, p2: 10, p3: 11, p4: 'awesome', p5: 'possum'};">C2 {p1: 9, p2: 10, p3: 11, p4: 'awesome', p5: 'possum'}</a>

You can see this in action below.

Customize the routing context

However, this default behavior can be changed by binding the context property of the load custom attribute explicitly. To this end, you need to bind the instance of IRouteContext in which you want to perform the navigation. The most straightforward way to select a parent routing context is to use the parent property of the IRouteContext. The current IRouteContext can be injected using the resolve(IRouteContext). Then one can use context.parent, context.parent?.parent etc. to select an ancestor context.

import { resolve } from '@aurelia/kernel';

export class ChildOne {
  private readonly parentCtx: IRouteContext = resolve(IRouteContext).parent;
}

Such ancestor context can then be used to bind the context property of the load attribute as follows.

<a load="route: r2; context.bind: parentCtx">c2</a>

The following live example demonstrate this behavior.

Note that even though the ChildOne defines a route with r2 route-id, specifying the context explicitly, instructs the router-lite to look for a route with r2 route-id in the parent routing context.

Using the IRouteContext#parent path to select the root routing context is somewhat cumbersome when you intend to target the root routing context. For convenience, the router-lite supports binding null to the context property which instructs the router to perform the navigation in the root routing context.

<a load="route: r2; context.bind: null">Go to root c2</a>

This is shown in the following example.

When the route context selection involves only ancestor context, then the ../ prefix can be used when using string instruction. This also works when using the route-id. The following code snippets shows, how the previous example can be written using the ../ prefix.

<a load="route: ../r2">c2</a>

active status

When using the load attribute, you can also leverage the bindable active property which is true whenever the associated route, bound to the href is active. In the following example, when a link in clicked and thereby the route is activated, the active* properties are bound from the views to true and thereby applying the .active-CSS-class on the a tags.

<style>
  a.active {
    font-weight: bolder;
  }
</style>

<nav>
  <a
    load="route:foo; params.bind:{id: 1}; active.bind:active1"
    active.class="active1"
    >foo/1</a
  >
  <a load="route:foo/2; active.bind:active2" active.class="active2">foo/2</a>
</nav>

<au-viewport></au-viewport>

This can also be seen in the live example below.

"active" CSS class

Using the Router API

Along with the custom attributes on the markup-side, the router-lite also offers the IRouter#load method that can be used to perform navigation, with the complete capabilities of the JavaScript at your disposal. To this end, you have to first inject the router into your component. This can be done by using the IRouter decorator on your component constructor method as shown in the example below.

import { resolve } from 'aurelia';
import { IRouter, IRouteableComponent } from '@aurelia/router-lite';

export class MyComponent {
  private readonly router: IRouter = resolve(IRouter);
}

Now you are ready to use the load method, with many supported overloads at your disposal. These are outlined below.

Using string instructions

The easiest way to use the load method is to use the paths directly.

router.load('c1')
router.load('c2')
router.load('c2/42')
router.load('c1+c2')
router.load('c1@vp2+c2@vp1')

With respect to that, this method supports the string instructions supported by the href and the load attribute. This is also shown in the example below.

// in ChildOne
router.load('c2');


// in ChildTwo
router.load('c1');
// in ChildOne
router.load('gc11', { context: this });

// in ChildTwo
router.load('gc21', { context: this });

An array of paths (string) can be used to load components into sibling viewports. The paths can be parameterized or not non-parameterized.

router.load(['c1', 'c2']);
router.load(['c1', 'c2/21']);

This is shown in the example below.

Using non-string routing instructions

The load method also support non-string routing instruction.

Using custom elements

You can use the custom element classes directly for which the routes have been configured. Multiple custom element classes can be used in an array to target sibling viewports.

router.load(ChildOne);
router.load([ChildOne, ChildTwo]);

router.load(GrandChildOneOne, { context: this });

This can be seen in action in the live example below.

Using custom element definitions

You can use the custom element definitions for which routes have been configured. Multiple definitions can be used in an array to target sibling viewports.

import { CustomElement } from '@aurelia/runtime-html';

router.load(CustomElement.getDefinition(ChildOne));
router.load([
  CustomElement.getDefinition(ChildOne),
  CustomElement.getDefinition(ChildTwo)
]);

router.load(
  CustomElement.getDefinition(GrandChildOneOne),
  { context: this }
);

This can be seen in action in the live example below.

Using a function to return the view-model class

router.load(() => ChildOne);
router.load([() => ChildOne, () => ChildTwo]);

router.load(() => GrandChildOneOne, { context: this });

This can be seen in action in the live example below.

Using import()

router.load(import('./child1'));          // uses the default or first non-default import
router.load([
  import('./child1'),
  import('./child2').then(m => m.Child2) // selective import
]);

This can be seen in action in the live example below.

Note that because invoking the import() function returns a promise, you can also use a promise directly with the load function.

router.load(Promise.resolve({ ChildOne }));

Using a viewport instruction

Any kind of routing instruction used for the load method is converted to a viewport instruction tree. Therefore, you can also use a (partial) viewport instruction directly with the load method. This offers maximum flexibility in terms of configuration, such as routing parameters, viewports, children etc. Following are few examples, how the viewport instruction API can be used.

// using a route-id
router.load({ component: 'c1' });

// using a class
router.load({ component: ChildTwo });

// load sibling routes
router.load([
  // use custom element definition
  { component: CustomElement.getDefinition(ChildOne) },
  // use a function returning class
  { component: () => ChildTwo, params: { id: 42 } },
]);

// load sibling routes with nested children and parameters etc.
router.load([
  // using path
  {
    component: 'c1',
    children: [{ component: GrandChildOneTwo }],
    viewport: 'vp2',
  },
  // using import
  {
    component: import('./child2'),
    params: { id: 21 },
    children: [{ component: GrandChildTwoTwo }],
    viewport: 'vp1',
  },
]);

This can be seen in the example below.

Using navigation options

Along with using the routing instructions, the load method allows you to specify different navigation options on a per-use basis. One of those, the context, you have already seen in the examples in the previous sections. This section describes other available options.

title

The title property allows you to modify the title as you navigate to your route. This looks like as follows.

router.load(Home, { title: 'Some title' });

Note that defining the title like this, overrides the title defined via the route configuration. This can also be seen in the action below where a random title is generated every time.

titleSeparator

router.load(Home, { titleSeparator: '-' });

This can also be seen in the action below where a random title separator is selected every time.

queryParams

This option lets you specify an object to be serialized to a query string. This can be used as follows.

// the generated URL: /home?foo=bar&fizz=buzz
router.load(
  'home',
  {
    queryParams: {
      foo: 'bar',
      fizz: 'buzz',
    }
  }
);

This can be seen in the live example below.

fragment

Like the queryParams, using the fragment option, you can specify the hash fragment for the new URL. This can be used as follows.

// the generated URL: /home#foobar
router.load(
  'home',
  {
    fragment: 'foobar'
  }
);

This can be seen in the live example below.

context

As by default, the load method performs the navigation relative to root context, when navigating to child routes, the context needs to be specified. This navigation option has also already been used in various examples previously. Various types of values can be used for the context.

The easiest is to use the custom element view model instance. If you are reading this documentation sequentially, then you already noticed this. An example looks like as follows.

router.load('child-route', { context: this });

Here is one of the previous example. Take a look at the child1.ts or child2.ts that demonstrates this.

You can also use an instance of IRouteContext directly. One way to grab the instance of IRouteContext is to get it inject via constructor using resolve(IRouteContext). An example looks like as follows.

import { resolve } from '@aurelia/kernel';
import { IRouteContext, IRouter, Params, route } from '@aurelia/router-lite';
import { customElement } from '@aurelia/runtime-html';

@customElement({ name: 'gc-21', template: 'gc21' })
class GrandChildTwoOne {}

@customElement({ name: 'gc-22', template: 'gc22' })
class GrandChildTwoTwo {}

@route({
  routes: [
    { id: 'gc21', path: ['', 'gc21'], component: GrandChildTwoOne },
    { id: 'gc22', path: 'gc22', component: GrandChildTwoTwo },
  ],
})
@customElement({
  name: 'c-two',
  template: `c2 <br>
  id: \${id}
  <nav>
    <button click.trigger="load('gc21', true)">Go to gc21</button>
    <button click.trigger="load('gc22', true)">Go to gc22</button>
    <button click.trigger="load('c1')"        >Go to c1  </button>
  </nav>
  <br>
  <au-viewport></au-viewport>`,
})
export class ChildTwo {
  private id: string;
  private readonly router: IRouter = resolve(IRouter);
  // injected instance of IRouteContext
  private readonly context: IRouteContext = resolve(IRouteContext);

  private load(route: string, useCurrentContext: boolean = false) {
    void this.router.load(
      route,
      useCurrentContext
        ? {
            // use the injected IRouteContext as navigation context.
            context: this.context
          }
        : undefined
    );
  }
  public loading(params: Params) {
    this.id = params.id ?? 'NA';
  }
}

You can see this in action below.

Using a custom element controller instance is also supported to be used as a value for the context option. An example looks as follows.

import { resolve } from 'aurelia';
import { IRouter, route } from '@aurelia/router-lite';
import {
  customElement,
  type ICustomElementController,
  type IHydratedCustomElementViewModel,
} from '@aurelia/runtime-html';

@customElement({ name: 'gc-11', template: 'gc11' })
class GrandChildOneOne {}

@customElement({ name: 'gc-12', template: 'gc12' })
class GrandChildOneTwo {}

@route({
  routes: [
    { id: 'gc11', path: ['', 'gc11'], component: GrandChildOneOne },
    { id: 'gc12', path: 'gc12', component: GrandChildOneTwo },
  ],
})
@customElement({
  name: 'c-one',
  template: `c1 <br>
  <nav>
    <button click.trigger="load('gc11', true)">Go to gc11</button>
    <button click.trigger="load('gc12', true)">Go to gc12</button>
    <button click.trigger="load('c2')"        >Go to c2  </button>
  </nav>
  <br>
  <au-viewport></au-viewport>`,
})
export class ChildOne implements IHydratedCustomElementViewModel {
  // set by aurelia pipeline
  public readonly $controller: ICustomElementController<this>;
  private readonly router: IRouter = resolve(IRouter);

  private load(route: string, useCurrentContext: boolean = false) {
    void this.router.load(
      route,
      useCurrentContext
        ? {
            // use the custom element controller as navigation context
            context: this.$controller
          }
        : undefined
    );
  }
}

You can see this in action below.

And lastly, you can use the HTML element as context. Following is live example of this.

historyStrategy

router.load('c1');
router.load('c2');

After this, if we issue the following instruction,

router.load('c3', { historyStrategy: 'replace' })

then performing a history.back() should load the c1 route, as the state for c2 is replaced.

transitionPlan

@route({
  transitionPlan: 'replace',
  routes: [
    {
      id: 'ce1',
      path: ['ce1/:id'],
      component: CeOne,
      transitionPlan: 'invoke-lifecycles',
    },
    {
      id: 'ce2',
      path: ['ce2/:id'],
      component: CeTwo,
      transitionPlan: 'replace',
    },
  ],
})
@customElement({
  name: 'my-app',
  template: `
<button click.trigger="navigate('ce1/42')">ce1/42 (default: invoke lifecycles)</button><br>
<button click.trigger="navigate('ce1/43')">ce1/43 (default: invoke lifecycles)</button><br>
<button click.trigger="navigate('ce1/44', 'replace')">ce1/44 (override: replace)</button><br>
<br>

<button click.trigger="navigate('ce2/42')">ce2/42 (default: replace)</button><br>
<button click.trigger="navigate('ce2/43')">ce2/43 (default: replace)</button><br>
<button click.trigger="navigate('ce2/44', 'invoke-lifecycles')">ce2/44 (override: invoke lifecycles)</button><br>

<au-viewport></au-viewport>
`,
})
export class MyApp {
  private readonly router: IRouter = resolve(IRouter);
  private navigate(
    path: string,
    transitionPlan?: 'replace' | 'invoke-lifecycles'
  ) {
    void this.router.load(
      path,
      transitionPlan ? { transitionPlan } : undefined
    );
  }
}

This can be seen in action below.

Redirection and unknown paths

For completeness it needs to be briefly discussed that apart from the explicit navigation instruction, there can be need to redirect the user to a different route or handle unknown routes gracefully. Other sections of the router-lite documentation discusses these topics in detail. Hence these topics aren't repeated here. Please refer to the linked documentations for more details.

Checking or using the current route while navigating

Sometimes, when navigating, you'll want to compare the route you're navigating to with the current one. This can help skip redundant navigations, read query parameters, or handle special cases. You can inject ICurrentRoute from @aurelia/router-lite and compare it:

import { IRouter, ICurrentRoute } from '@aurelia/router-lite';
import { resolve } from '@aurelia/kernel';

export class MyApp {
  private readonly router = resolve(IRouter);
  private readonly currentRoute = resolve(ICurrentRoute);

  public navigateToAbout() {
    if (this.currentRoute.path === 'about') {
      console.log('Already on "about" page');
      return;
    }
    this.router.load('about');
  }

  public logParams() {
    // For example, you might want the existing query:
    console.log('Query string is:', this.currentRoute.url.split('?')[1]);
  }
}

While configuring routes, an can be set explicitly. This id can also be used with the href attribute. This is shown in the example below.

Note that using the route-id of a parameterized route with the href attribute might be limiting or in some cases non-operational as with href attribute there is no way to specify the parameters for the route separately. This case is handled by the .

You can target and/or viewports. To this end, you can use the following syntax.

Contextually, note that the also demonstrates the behavior of navigating in the current context. In that example, the root component uses r1, and r2 as route identifiers, which are the same identifiers used in the children to identify their respective child-routes. The route-ids are used in the markup with the href attributes. Despite being the same route-ids, the navigation works because unless specified otherwise, the routing instructions are constructed under the current routing context.

By default the router-lite enables usage of the href custom attribute, as that ensures that the router-lite handles the routing instructions by default. There might be cases, where you want to avoid that. If you want to globally deactivate the usage of href, then you can customize the router configuration by setting false to the .

Although the usage of href is the most natural choice, it has some limitations. Firstly, it allows navigating in the . However, a bigger limitation might be that the href allows usage of only string values. This might be bit sub-optimal when the routes have parameters, as in that case you need to know the order of the parameterized and static segments etc. to correctly compose the string path. In case the order of those segments are changed, it may cause undesired or unexpected results if your application.

The bindable route property in the load attribute supports binding a class instead of route-id. The following example demonstrates using the classes (child1, child2) directly, instead of using the route-id.

Just like the href attribute, the load attribute also supports navigating in the by default. The following example shows this where the root component has two child-routes with r1 and r2 route-ids and the child-components in turn defines their own child-routes using the same route-ids. The load attributes also use the route-ids as routing instruction. The routing works in this case, because the routes are searched in the same routing context.

Note that the also offers a .

The active bindable can be used for other purposes, other than adding CSS classes to the element. However, if that's what you need mostly the active property for, you may choose to configure the in the router configuration. When configured, the load custom attribute will add that configured class to the element when the associated routing instruction is active.

There is a major important difference regarding the context selection in the IRouter#load method and the href and load custom attributes. By default, the custom attributes performs the navigation in the current routing context (refer the and documentation). However, the load method always use the root routing context to perform the navigation. This can be observed in the ChildOne and ChildTwo components where the load method is used the following way to navigate from ChildOne to ChildTwo and vice versa. As the load API uses the the root routing context by default, such routing instructions works. In comparison, note that with href we needed to use the .. prefix or with load method we needed to set the context to null.

However, on the other hand, you need to specify the routing context, when you want to navigate inside the current routing context. The most obvious use case is when you issue routing instruction for the child-routes inside a parent component. This can also be observed in ChildOne and ChildTwo components where a specific context is used as part of the to navigate to the child routes.

Similar to , for load you can use a function that returns a class as routing instruction. This looks like as follows.

Similar to , for load you can use an import() statement to import a module. This looks like as follows.

As the name suggests, this provides a configuration option to customize the separator for the . By default router-lite uses | (pipe) as separator. For example if the root component defines a title 'Aurelia' and has a route /home with title Home, then the resulting title would be Home | Aurelia when navigating to the route /home. Using this option, you can customize the separator.

Using this navigation option, you can override the . Let us consider the example where three routes c1, c2, and c3 are configured with the push history strategy. Let us also assume that the following navigation instructions have already taken place.

Using this navigation option, you can override the per routing instruction basis. The following example demonstrates that even though the routes are configured with a specific transition plans, using the router API, the transition plans can be overridden.

Fallback using the

Fallback using the

configured transition plan
load attribute
example involving route-id
current routing context
the params-example
current routing context
href
load attribute
navigation options
navigation model
Logorouter-lite - getting started - StackBlitzStackBlitz
Logorouter-lite - href with bound parameter - StackBlitzStackBlitz
Logorouter-lite - href - route-id - StackBlitzStackBlitz
isActive property
useHref configuration option
activeClass property
configured history strategy
Logorouter-lite - named-sibling-viewport - href - StackBlitzStackBlitz
Logorouter-lite - href - hierarchical - current-context - StackBlitzStackBlitz
Logorouter-lite - bypassing href - StackBlitzStackBlitz
Logorouter-lite - load - string-instructions - StackBlitzStackBlitz
Logorouter-lite - load - params - StackBlitzStackBlitz
Logorouter-lite - load - class-as-route - StackBlitzStackBlitz
Logorouter-lite - load - current context - StackBlitzStackBlitz
Logorouter-lite - load - parent context - StackBlitzStackBlitz
Logorouter-lite - load - null/root context - StackBlitzStackBlitz
Logorouter-lite - load - active - StackBlitzStackBlitz
Logorouter-lite - IRouter#load - string-instructions - StackBlitzStackBlitz
Logorouter-lite - IRouter#load - array-of-paths - siblings - StackBlitzStackBlitz
Logorouter-lite - IRouter#load - CE - StackBlitzStackBlitz
id for the route
route configuration
route configuration
title parts
Redirection documentation
route configuration
Logorouter-lite - IRouter#load - CE Definition - StackBlitzStackBlitz
Logorouter-lite - IRouter#load - component factory - StackBlitzStackBlitz
Logorouter-lite - IRouter#load - import() - StackBlitzStackBlitz
Logorouter-lite - IRouter#load - viewport instruction - StackBlitzStackBlitz
Logorouter-lite - load - nav options - title - StackBlitzStackBlitz
Logorouter-lite - load - nav options - title separator - StackBlitzStackBlitz
Logorouter-lite - load - nav options - query - StackBlitzStackBlitz
Logorouter-lite - load - nav options - query - StackBlitzStackBlitz
Logorouter-lite - IRouter#load - string-instructions - StackBlitzStackBlitz
Logorouter-lite - IRouter#load - context - IRouteContext - StackBlitzStackBlitz
Logorouter-lite - IRouter#load - context - controller - StackBlitzStackBlitz
Logorouter-lite - IRouter#load - context - element - StackBlitzStackBlitz
Logorouter-lite - transitionPlan - nav opt - StackBlitzStackBlitz
named
sibling
viewport attribute