Search

#### Docs

- Guide
  - Overview
  - Setup
  - Learning Angular
  - Architecture
  - Displaying Data
  - User Input
  - Forms
  - Dependency Injection
  - Template Syntax
- Tutorial
  - Introduction
  - 0. The Starter App
  - 1. The Hero Editor
  - 2. Master/Detail
  - 3. Multiple Components
  - 4. Services
  - 5. Routing
  - 6. HTTP
- Advanced
  - Attribute Directives
  - Component Styles
  - Deployment
  - Hierarchical Injectors
  - HTTP Client
  - Lifecycle Hooks
  - Pipes
  - Router
  - Security
  - Structural Directives
  - Testing

#### Components

- Components Gallery

#### Resources

- Cheat Sheet
- Glossary
- FAQ
- Tools
- Community and Support

#### Reference

- Videos
- API Documentation

new_releases We're currently in the progress of migrating this site from Angular version 5.3.1 to 7.0.0. Package versions might be out-of-date or inconsistent! Visit the repo for more info.

# Routing Overview (DRAFT) 6.0

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

<?code-excerpt path-base=”examples/ng/doc/router”?> <?code-excerpt replace=”/_\d((.template)?.dart)/$1/g”?>

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:

<?code-excerpt “pubspec.yaml (dependencies)” region=”dependencies-wo-forms” replace=”/angular_.+/[!$&!]/g” title?>

      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:

<?code-excerpt “lib/app_component_1.dart (angular_router)”?>

      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:

- Choose a location strategy.
- Register appropriate router providers when launching your app.
- Ensure that each routing component has metadata listing the router directives used by the component.

## 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:

<?code-excerpt path-base=”examples/ng/doc/toh-5”?>

- Define route paths:

  <?code-excerpt “lib/src/route_paths.dart” region=”v1” plaster=”none” title?>

        import 'package:ngrouter/ngrouter.dart';

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

- Define route definitions:

  <?code-excerpt “lib/src/routes.dart (a first route)” plaster=”none” title?>

        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:

<?code-excerpt “lib/app_component.dart (routes and template)” plaster=”none” remove=”/Hero|nav|routerLink|title/” replace=”/(\s+)(.router-outlet.*)/$1…$1[!$2!]/g” title?>

      import 'src/routes.dart';

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

For details, see RouterOutlet.

<?code-excerpt path-base=”examples/ng/doc/router”?>

### Router links

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.

<?code-excerpt “lib/app_component_1.dart (template and styles)” region=”template” replace=”/[routerLink(Active)?]/[!$&!]/g” title?>

      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.