README.md

Angular Component Router

A declarative router for Angular applications.

Install

Use your package manager of choice to install the package.

npm install @angular-component/router

OR

yarn add @angular-component/router

Installation with ng add

You can use ng add to install the package by using the command below.

ng add @angular-component/router

The above command will install the package, and add the ComponentRouterModule import in the AppModule.

Usage

To register the Router, add the ComponentRouterModule.forRoot() to your AppModule imports.

import { ComponentRouterModule } from '@angular-component/router';

@NgModule({
  imports: [
    // ... other imports
    ComponentRouterModule.forRoot(),
  ],
})
export class AppModule {}

Or in a feature module

import { ComponentRouterModule } from '@angular-component/router';

@NgModule({
  imports: [
    // ... other imports
    ComponentRouterModule,
  ],
})
export class FeatureModule {}

Usage with Standalone Features (v14+)

After your components are registered, use the Router and Route components to register some routes.

<router>
  <!-- For nested routes use exact: false -->
  <route path="/blog" [exact]="false">
    <app-blog *routeComponent></app-blog>
  </route>
  <route path="/posts/:postId">
    <app-post *routeComponent></app-post>
  </route>
  <route path="/about">
    <app-about *routeComponent></app-about>
  </route>
  <route path="/" redirectTo="/blog"> </route>
  <route path="/" [exact]="false">
    <app-page-not-found *routeComponent></app-page-not-found>
  </route>
</router>

Route sorting

Angular routing is sorting the routes upon registration, based on priority. The order in which the routes are defined in your template is therefore not important.

The following two examples will give the same results

<router>
  <route path="/blog" [exact]="false">
    <app-blog *routeComponent></app-blog>
  </route>
  <route path="/" redirectTo="/blog"></route>
  <route path="/" [exact]="false">
    <app-page-not-found *routeComponent></app-page-not-found>
  </route>
</router>

and

<router>
  <route path="/" [exact]="false">
    <app-page-not-found *routeComponent></app-page-not-found>
  </route>
  <route path="/" redirectTo="/blog"></route>
  <route path="/blog" [exact]="false">
    <app-blog *routeComponent></app-blog>
  </route>
</router>

The sorting algorithm has only a few rules (ordered by importance):

• Named routes (e.g. /blog) have priority over root route (/)
• Static routes (e.g. /blog/view) have priority over parametrized (e.g. /blog/:id)
• Exact route (with exact set to true or omitted) has priority over non-exact (with exact set to false)
• Longer paths have priority over shorter

Route restrictions

Implementing the route restriction is as simple as adding a structural directive on a route component

<router>
  <route path="/admin" *ngIf="user.isAuthenticated$ | async">
    <app-admin *routeComponent></app-admin>
  </route>
  <route path="/admin" *ngIf="!(user.isAuthenticated$ | async)">
    <app-login *routeComponent></app-login>
  </route>
</router>

The restriction doesn't stop the navigation. It simply removes the route from the configuration so the next eligible route will pick it up.

Navigating with Links

Use the linkTo directive with a full or relative path to register links handled by the router.

<a linkTo="/">Home</a>
<a linkTo="/about">About</a>
<a linkTo="/blog">Blog</a>
<a linkTo="../other"></a>

Adding classes to active links

To add classes to links that match the current URL path, use the linkActive directive.

<a linkTo="/" linkActive="active">Home</a>
<a linkTo="/about" linkActive="active">About</a>
<a linkTo="/blog" linkActive="active" [activeOptions]="{ exact: false }"
  >Blog</a
>

Using the Router service

To navigate from a component class, or get global route information, such as the current URL, or hash fragment, inject the Router service.

import { Component } from '@angular/core';
import { Router } from '@angular-component/router';

@Component({...})
export class MyComponent {
  constructor(private router: Router) {}

  ngOnInit() {
    this.router.url$.subscribe();
    this.router.hash$.subscribe();
  }

  goHome() {
    this.router.go('/');
  }

  goForward() {
    this.router.forward();
  }

  goBack() {
    this.router.back();
  }
}

Using Route Params

To get the route params, inject the RouteParams observable. Provide a type for the shape of the route params object.

import { Component } from '@angular/core';
import { RouteParams } from '@angular-component/router';

@Component({...})
export class MyComponent {
  constructor(
    private routeParams$: RouteParams<{ postId: string }>
  ) {}

  ngOnInit() {
    this.routeParams$.subscribe(console.log);
  }
}

Using Query Params

To get the route params, inject the QueryParams observable. Provide a type for the shape of the query params object.

import { Component } from '@angular/core';
import { QueryParams } from '@angular-component/router';

@Component({...})
export class MyComponent {
  constructor(
    private queryParams$: QueryParams<{ debug: boolean }>
  ) {}

  ngOnInit() {
    this.queryParams$.subscribe(console.log);
  }
}

Lazy Loading Modules

To lazy load a module, use the load binding on the route component.

import { Component } from '@angular/core';

@Component({
  template: `
    <router>
      <route path="/lazy" [exact]="false" [load]="modules.lazy"> </route>
    </router>
  `,
})
export class MyComponent {
  modules = {
    lazy: () => import('./lazy/lazy.module').then((m) => m.LazyModule),
  };
}

Register a component to register the child routes.

import { Component } from '@angular/core';

@Component({
  template: `
    <router>
      <route path="/">
        <app-lazy *routeComponent></app-lazy>
      </route>
      <route path="/" [exact]="false" redirectTo="/404"> </route>
    </router>
  `,
})
export class LazyRouteComponent {}

Implement the ModuleWithRoute interface for the route component to render after the module is loaded.

import { NgModule } from '@angular/core';
import { ModuleWithRoute } from '@angular-component/router';

@NgModule({
  declarations: [LazyRouteComponent, LazyComponent],
})
export class LazyModule implements ModuleWithRoute {
  routeComponent = LazyRouteComponent;
}

Lazy Loading Components

To lazy load a component, use the load binding on the route component.

import { Component } from '@angular/core';

@Component({
  template: `
    <router>
      <route path="/lazy" [load]="components.lazy"> </route>
    </router>
  `,
})
export class MyComponent {
  components = {
    lazy: () => import('./lazy/lazy.component').then((m) => m.LazyComponent),
  };
}

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Brandon 💻 📖 ⚠️

Miroslav Jonaš 💻 📖 ⚠️

Santosh Yadav 💻 📖

Kyle Cannon 💻

This project follows the all-contributors specification. Contributions of any kind welcome!