angulardart.xyz

Search

Docs

Components

Resources

Reference

On this page

Routing Overview (DRAFT) 6.0

If you notice any issues with this page, please report them.

This is a DRAFT of the router pages, which are still being actively updated. Most of the content is accurate, but the sample is still being reworked and enhanced. Feedback is welcome.

The Angular router enables navigation from one view to the next as users perform app tasks.

This guide covers the router’s primary features, illustrating them through the evolution of a small app that you can run live (view source).

Overview

The browser is a familiar model of app navigation:

  • Enter a URL in the address bar and the browser navigates to a corresponding page.
  • Click links on the page and the browser navigates to a new page.
  • Click the browser’s back and forward buttons and the browser navigates backward and forward through the history of pages you’ve seen.

The Angular router borrows from this model. It can interpret a browser URL as an instruction to navigate to a client-generated view. It can pass optional parameters along to the supporting view component that help it decide what specific content to present. You can bind the router to links on a page and it will navigate to the appropriate app view when the user clicks a link. You can navigate imperatively when the user clicks a button, selects from a drop box, or in response to some other stimulus from any source. And the router logs activity in the browser’s history journal so the back and forward buttons work as well.

Setup overview

Add angular_router

Router functionality is in the angular_router library, which comes in its own package. Add the package to the pubspec dependencies:

pubspec.yaml (dependencies)

dependencies:
  angular: ^6.0.1
  # ···
  angular_router: ^2.0.0-alpha+22

In any Dart file that makes use of router features, import the router library:

import 'package:angular_router/angular_router.dart';

Register providers and list directives

If you’re already familiar with Angular routing, here’s a reminder of what you need to do:

Basic feature overview

This guide proceeds in phases, marked by milestones, starting from a skeletal app and building toward a modular, multi-view design with child routes. This overview of core router concepts will help orient you to the details that follow.

<base href>

Most routing apps have a <base href="..."> element in the index.html <head> to tell the router how to compose navigation URLs. For details, see Set the base href.

Routes

Routes tell the router which views to display when a user clicks a link or pastes a URL into the browser address bar. To configure routes you’ll need to do the following:

  • Define route paths:

    lib/src/route_paths.dart

    import 'package:ngrouter/ngrouter.dart';

class RoutePaths {
  static final heroes = RoutePath(path: 'heroes');
}

  • Define route definitions:

    lib/src/routes.dart (a first route)

    import 'package:ngrouter/ngrouter.dart';

import 'route_paths.dart';
import 'hero_list_component.template.dart' as hero_list_template;

export 'route_paths.dart';

class Routes {
  static final heroes = RouteDefinition(
    routePath: RoutePaths.heroes,
    component: hero_list_template.HeroListComponentNgFactory,
  );

  static final all = <RouteDefinition>[
    heroes,
  ];

  static final heroRoute = <RouteDefinition>[hero];
}

  • Bind the route definitions to a router outlet, as illustrated next.

Router outlet

When you visit localhost:8080/#/heroes, the router matches the URL with the heroes route path, and displays a HeroListComponent immediately below the <router-outlet> in the routing component template:

lib/app_component.dart (routes and template)

import 'src/routes.dart';

@Component(
  template: '''
    ...
    <router-outlet [routes]="Routes.all"></router-outlet>
  ''',
  directives: [routerDirectives],
  exports: [RoutePaths, Routes],
)
class AppComponent {
}

For details, see RouterOutlet.

A RouterLink directive on an anchor tag gives the router control over the anchor. Bind each RouterLink directive to a template expression that evaluates to a URL.

lib/app_component.dart (template and styles)

template: '''
  <h1>Angular Router</h1>
  <nav>
    <a [routerLink]="RoutePaths.crises.toUrl()"
       [routerLinkActive]="'active-route'">Crisis Center</a>
    <a [routerLink]="RoutePaths.heroes.toUrl()"
       [routerLinkActive]="'active-route'">Heroes</a>
  </nav>
  <router-outlet [routes]="Routes.all"></router-outlet>
''',
styles: ['.active-route {color: #039be5}'],

A RouterLinkActive will apply the named CSS class to the anchor whose link is active. This helps visually distinguish the active links.

For details, see RouterLinks.

Summary

Here are the key router terms and their meanings.

Router Part Meaning
Router Displays the app component for the active URL. Manages navigation from one component to the next.
Routing component An Angular component with a <router-outlet> that displays views based on router navigations.
Route A kind of RouteDefinition. Defines how the router should navigate to a component based on a URL pattern. Most routes consist of a path, a route name, and a component type.
RouteDefinition Defines how the router should navigate to a component based on a URL pattern.
RouterOutlet The directive (<router-outlet>) that marks where the router should display a views.
RouterLink The directive for binding a clickable HTML element to a route. Clicking an element with a routerLink directive triggers a navigation.

What next?

The rest of this guide describes the development of a multi-page routed app (view source) through a sequence of milestones. Each milestone highlights specific design decisions and introduces new key features of the router.