Aurelia Child Routers and Nested Routes

In this tutorial, you will learn about Aurelia Child Routers and Nested Routes. We cover key concepts, practical examples, and best practices to help you master this topic.

Aurelia child routers let you delegate routing responsibility to sub-components, creating nested navigation hierarchies that keep your application modular and maintainable.

What You'll Learn

• Configuring child routers in Aurelia components
• Sharing data between parent and child routes
• Lazy-loading child route modules
• Handling deep-linking with nested URLs

Why It Matters

Single-level routing works for small apps, but real-world applications often have multiple sections (admin, dashboard, settings) that each need their own navigation structure. Child routers let each section manage its own routes independently.

Real-World Use

A content management system where the main router handles top-level pages (Dashboard, Content, Users), and the Content section has its own child router managing Articles, Categories, and Media sub-sections.

Nested Route Architecture

flowchart TD
    A[Root Router] --> B[Route: /dashboard]
    A --> C[Route: /content]
    A --> D[Route: /users]
    C --> E[Child Router in Content Section]
    E --> F[Route: /articles]
    E --> G[Route: /categories]
    E --> H[Route: /media]
    F --> I[Route: /articles/:id]
    style E fill:#e6f3ff,stroke:#4a90d9,stroke-width:2px

Configuring a Child Router

Add a configureRouter method to any component to give it its own router:

import { autoinject } from 'aurelia-framework';
import { Router, RouterConfiguration } from 'aurelia-router';

@autoinject
export class ContentSection {
  router: Router;

  configureRouter(config: RouterConfiguration, router: Router): void {
    config.map([
      { route: '',          moduleId: './content-dashboard', title: 'Content Overview' },
      { route: 'articles',  moduleId: './articles',          title: 'Articles' },
      { route: 'categories', moduleId: './categories',       title: 'Categories' },
      { route: 'media',     moduleId: './media',             title: 'Media' }
    ]);
    this.router = router;
  }
}

Parent-Child View Setup

The parent view must include a <router-view> element for the child router to render into:

<template>
  <div class="content-section">
    <nav>
      <a repeat.for="nav of router.navigation"
         href.bind="nav.href">${nav.title}</a>
    </nav>
    <div class="child-content">
      <router-view></router-view>
    </div>
  </div>
</template>

Expected output: Navigation links for Content Dashboard, Articles, Categories, and Media render at the top, with child route content below.

Lazy-Loading Child Route Modules

Use dynamic import() to split child route bundles:

configureRouter(config: RouterConfiguration, router: Router): void {
  config.map([
    {
      route: 'articles',
      moduleId: () => import('./articles'),
      title: 'Articles'
    },
    {
      route: 'articles/:id',
      moduleId: () => import('./article-detail'),
      title: 'Article Detail'
    }
  ]);
  this.router = router;
}

Expected output: The articles and article-detail modules are fetched only when the user navigates to those routes, reducing the initial bundle size.

Passing Data Between Parent and Child Routers

Use the activationStrategy and route parameters to share context:

// Parent section route config
config.map([
  {
    route: 'content',
    moduleId: './content-section',
    title: 'Content',
    settings: { sectionId: 42 }
  }
]);

// In child component - access parent settings
activate(params, routeConfig) {
  this.sectionId = routeConfig.settings.sectionId;
}

Common Mistakes

1. Missing router-view in child component - Without <router-view>, the child router has nowhere to render its routes.

2. Route collisions between parent and child - When a parent route like content/articles and a child route articles overlap, the child route segment is appended to the parent's path. Ensure the combined path is unique.

3. Forgetting to import Router in child - The configureRouter method only works when Router and RouterConfiguration are properly imported from aurelia-router.

4. Hard-coding navigation paths - Always use router.navigation to generate links instead of hard-coded strings, so paths update automatically when routes change.

5. Not handling empty child routes - Provide a default route (route: '') for child routers so navigation to the parent section shows useful content instead of a blank area.

Practice Questions

1. What method must a component implement to have its own child router?
2. How do you prevent a child router module from being loaded until the user navigates to it?
3. What is the purpose of the settings property in a route configuration object?
4. How can a child component access data passed from its parent route configuration?
5. What happens if you omit activationStrategy when using parameterized child routes?

Challenge: Create a settings section with a child router containing three tabs: Profile, Security, and Notifications. The Security tab should have its own sub-child router for Password Change and Two-Factor Auth.

FAQ

Mini Project

Build a settings panel with a child router that manages three tabs: Profile, Notifications, and Security. The Security tab should contain a sub-child router for Password and Two-Factor Auth sections. Apply activation strategies to preserve form state when switching between tabs.

What's Next

Now that you can nest routes, explore how Aurelia's HTTP client integrates with your routed application to fetch data from remote APIs.