Routing Overview 4.0
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
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.
In any Dart file that makes use of router features, import the router library:
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 bootstrapping your app.
- Ensure that each routing component has metadata listing the router directives used by the component.
For details, see Declaring router providers and directives.
Basic feature overview
This guide proceeds in phases, marked by milestones, starting from a simple two-pager 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.
Most routing apps have a
<base href="..."> element in the
to tell the router how to compose navigation URLs.
For details, see Set the base href.
When the browser’s URL changes, the router looks for a corresponding
from which it can determine the component to display.
A router has no routes until you configure it.
The following example creates some route definitions. It illustrates
the preferred way of simultaneously creating a router and
adding its routes using a
applied to the router’s host component:
There are several flavors of
The most common, illustrated above, is a named
Route which maps a URL path to a component.
When the browser URL for this app becomes
the router matches that URL to the
Heroes and displays the
RouterOutlet that you’ve placed in the host view’s HTML.
Now you have routes configured and a place to render them, but how do you navigate? The URL could arrive directly from the browser address bar. But most of the time you navigate as a result of some user action such as the click of an anchor tag.
Consider the following template:
RouterLink directives on the anchor tags give the router control over those elements.
You bind each
RouterLink directive to a template expression that
returns the route link parameters as a link parameters list.
The router resolves each link parameters list into a complete URL.
RouterLink directive also helps visually distinguish the anchor for the currently selected active route.
The router adds the
router-link-active CSS class to the element when the associated router link becomes active.
As illustrated above, you can define this style alongside the template in the
The app has a configured router.
The shell component has a
RouterOutlet where it can display views produced by the router.
RouterLinks that users can click to navigate via the router.
Here are the key router terms and their meanings:
||Displays the app component for the active URL. Manages navigation from one component to the next.|
Configures a router with a
||Defines how the router should navigate to a component based on a URL pattern.|
A kind of
The directive (
The directive for binding a clickable HTML element to
a route. Clicking an element with a
|Link parameters list||
A list that the router interprets as a routing instruction.
You can bind that list to a
An Angular component with a
The sample app
This guide describes the development of a multi-page routed sample app. Along the way, it highlights design decisions and describes key features of the router.
The guide proceeds as a sequence of milestones as if you were building the app step-by-step. But, it is not a tutorial and it glosses over details of Angular app construction that are more thoroughly covered elsewhere in the documentation.
The full source for the final version of the app can be seen and downloaded from the
The sample app in action
Imagine an app that helps the Hero Employment Agency run its business. Heroes need work and the agency finds crises for them to solve.
The app has these main features:
- A Crisis Center for maintaining the list of crises for assignment to heroes.
- A Heroes area for maintaining the list of heroes employed by the agency.
Try it by clicking on this
Select one hero and the app takes you to a hero editing screen.
Alter the name. Click the “Back” button and the app returns to the heroes list which displays the changed hero name. Notice that the name change took effect immediately.
Had you clicked the browser’s back button instead of the “Back” button, the app would have returned you to the heroes list as well. Angular app navigation updates the browser history as normal web navigation does.
Now click the Crisis Center link for a list of ongoing crises.
Select a crisis and the app takes you to a crisis editing screen. The Crisis Detail appears in a child view on the same page, beneath the list.
Alter the name of a crisis. Notice that the corresponding name in the crisis list does not change.
Unlike Hero Detail, which updates as you type, Crisis Detail changes are temporary until you either save or discard them by pressing the “Save” or “Cancel” buttons. Both buttons navigate back to the Crisis Center and its list of crises.
Do not click either button yet. Click the browser back button or the “Heroes” link instead.
Up pops a dialog box.
You can select “OK” and lose your changes or click “Cancel” and continue editing.
Behind this behavior is the router’s
The hook gives you a chance to clean-up or ask the user’s permission
before navigating away from the current view.