Getting started

Bundler note: These examples import '.html' files as raw strings (showing '?raw' for Vite/esbuild). Configure your bundler as described in Importing external HTML templates with bundlers so the imports resolve to strings on Webpack, Parcel, etc.

Routing with Aurelia feels like a natural part of the framework. It can easily be implemented into your applications in a way that feels familiar if you have worked with other frameworks and library routers. Here is a basic example of routing in an Aurelia application using router.

The following getting started guide assumes you have an Aurelia application already created. If not, consult our Quick Start to get Aurelia installed in minutes.

Installation

npm i @aurelia/router

Configure the router

To use the router, we have to register it with Aurelia. We do this at the bootstrapping phase.

main.ts

import Aurelia from 'aurelia';
import { RouterConfiguration } from '@aurelia/router';
import { MyApp } from './my-app';

Aurelia
  .register(RouterConfiguration.customize({
      useUrlFragmentHash: true, // <-- enables the routing using the URL `hash`
    }))
  .app(MyApp)
  .start();

To know more about the different configuration options for router, please refer the documentation on that topic.

Create the routable components

For this example, we have a root component which is MyApp. And then we are going to define two routes for the root component, namely home and about.

Let us define these components first.

home.ts

import { customElement } from '@aurelia/runtime-html';
import template from './home.html?raw';

@customElement({ name: 'ho-me', template })
export class Home {
  private readonly message: string = 'Welcome to Aurelia2 router!';
}

home.html

about.ts

import { customElement } from '@aurelia/runtime-html';
import template from './about.html?raw';

@customElement({ name: 'ab-out', template })
export class About {
  private readonly message = 'Aurelia2 router is simple';
}

about.html

Configure the routes

With the routable components in place, let's define the routes. To this end, we need to add the route configurations to our root component MyApp.

my-app.ts

import { customElement } from '@aurelia/runtime-html';
import { route } from '@aurelia/router';
import template from './my-app.html?raw';
import { Home } from './home';
import { About } from './about';

@route({
  routes: [
    {
      path: ['', 'home'],
      component: Home,
      title: 'Home',
    },
    {
      path: 'about',
      component: About,
      title: 'About',
    },
  ],
})
@customElement({ name: 'my-app', template })
export class MyApp {}

my-app.html

There are couple of stuffs to note here. We start by looking at the configurations defined using the @route decorator where we list out the routes under the routes property in the configuration object in the @route decorator. The most important things in every route configurations are the path and the component properties. This instructs the router to use the defined component in the viewport when it sees the associated path.

To know more about configuring routes, please refer to the respective documentation.

The viewport is specified in the view (see my-app.html) by using the <au-viewport> custom element. For example, the router will use this element to display the Home component when it sees the / (the empty path) or the /home paths.

The nav>a elements are added to navigate from one view to another.

See this in action:

router-lite - getting started - StackBlitzStackBlitz

Using pushstate

If you have opened the demo then you can notice that the URL in the address bar or the URLs in the nav>a elements contains a # (example: /#home, /#about etc.). Depending on your project need and esthetics you may want to get rid of the #-character. To this end, you need set the useUrlFragmentHash to false, which is also the default.

Live examples

For the documentation of router, many live examples are prepared. It is recommended to use the live examples as you read along the documentation. However, if you are feeling adventurous enough to explore the features by yourself, here is the complete collection of the live examples at your disposal.

The examples are created using StackBlitz. Sometimes, you need to open the examples in a new tab to see changes in the URL, title etc. To this end, copy the URL appearing on the address bar on the right pane and open that in a new tab.