This is the archived documentation for Angular v5. Please visit angular.io to see documentation for the current version of Angular.

Router

npm Package @angular/router
Module import { Router } from '@angular/router';
Source router/src/router.ts
NgModule RouterModule

Provides the navigation and url manipulation capabilities.

See Routes for more details and examples.

Overview

      
      class Router {
  constructor(rootComponentType: Type<any> | null, urlSerializer: UrlSerializer, rootContexts: ChildrenOutletContexts, location: Location, injector: Injector, loader: NgModuleFactoryLoader, compiler: Compiler, config: Routes)
  get events: Observable<Event>
  get routerState: RouterState
  errorHandler: ErrorHandler
  navigated: boolean
  urlHandlingStrategy: UrlHandlingStrategy
  routeReuseStrategy: RouteReuseStrategy
  onSameUrlNavigation: 'reload' | 'ignore'
  paramsInheritanceStrategy: 'emptyOnly' | 'always'
  config: Routes
  initialNavigation(): void
  setUpLocationChangeListener(): void
  get url: string
  resetConfig(config: Routes): void
  ngOnDestroy(): void
  dispose(): void
  createUrlTree(commands: any[], navigationExtras: NavigationExtras = {}): UrlTree
  navigateByUrl(url: string | UrlTree, extras: NavigationExtras = { skipLocationChange: false }): Promise<boolean>
  navigate(commands: any[], extras: NavigationExtras = { skipLocationChange: false }): Promise<boolean>
  serializeUrl(url: UrlTree): string
  parseUrl(url: string): UrlTree
  isActive(url: string | UrlTree, exact: boolean): boolean
}
    

Constructor

      
      constructor(rootComponentType: Type<any> | null, urlSerializer: UrlSerializer, rootContexts: ChildrenOutletContexts, location: Location, injector: Injector, loader: NgModuleFactoryLoader, compiler: Compiler, config: Routes)
    

Creates the router service.

Members

      
      get events: Observable<Event>
    

      
      get routerState: RouterState
    

      
      errorHandler: ErrorHandler
    

Error handler that is invoked when a navigation errors.

See ErrorHandler for more information.


      
      navigated: boolean
    

Indicates if at least one navigation happened.


      
      urlHandlingStrategy: UrlHandlingStrategy
    

Extracts and merges URLs. Used for AngularJS to Angular migrations.


      
      routeReuseStrategy: RouteReuseStrategy
    

      
      onSameUrlNavigation: 'reload' | 'ignore'
    

Define what the router should do if it receives a navigation request to the current URL. By default, the router will ignore this navigation. However, this prevents features such as a "refresh" button. Use this option to configure the behavior when navigating to the current URL. Default is 'ignore'.


      
      paramsInheritanceStrategy: 'emptyOnly' | 'always'
    

Defines how the router merges params, data and resolved data from parent to child routes. Available options are:

  • 'emptyOnly', the default, only inherits parent params for path-less or component-less routes.
  • 'always', enables unconditional inheritance of parent params.

      
      config: Routes
    

      
      initialNavigation(): void
    

Sets up the location change listener and performs the initial navigation.


      
      setUpLocationChangeListener(): void
    

Sets up the location change listener.


      
      get url: string
    

The current url


      
      resetConfig(config: Routes): void
    

Resets the configuration used for navigation and generating links.

Usage

      
      router.resetConfig([
 { path: 'team/:id', component: TeamCmp, children: [
   { path: 'simple', component: SimpleCmp },
   { path: 'user/:name', component: UserCmp }
 ]}
]);
    

      
      ngOnDestroy(): void
    

      
      dispose(): void
    

Disposes of the router


      
      createUrlTree(commands: any[], navigationExtras: NavigationExtras = {}): UrlTree
    

Applies an array of commands to the current url tree and creates a new url tree.

When given an activate route, applies the given commands starting from the route. When not given a route, applies the given command starting from the root.

Usage

      
      // create /team/33/user/11
router.createUrlTree(['/team', 33, 'user', 11]);

// create /team/33;expand=true/user/11
router.createUrlTree(['/team', 33, {expand: true}, 'user', 11]);

// you can collapse static segments like this (this works only with the first passed-in value):
router.createUrlTree(['/team/33/user', userId]);

// If the first segment can contain slashes, and you do not want the router to split it, you
// can do the following:

router.createUrlTree([{segmentPath: '/one/two'}]);

// create /team/33/(user/11//right:chat)
router.createUrlTree(['/team', 33, {outlets: {primary: 'user/11', right: 'chat'}}]);

// remove the right secondary node
router.createUrlTree(['/team', 33, {outlets: {primary: 'user/11', right: null}}]);

// assuming the current url is `/team/33/user/11` and the route points to `user/11`

// navigate to /team/33/user/11/details
router.createUrlTree(['details'], {relativeTo: route});

// navigate to /team/33/user/22
router.createUrlTree(['../22'], {relativeTo: route});

// navigate to /team/44/user/22
router.createUrlTree(['../../team/44/user/22'], {relativeTo: route});
    

      
      navigateByUrl(url: string | UrlTree, extras: NavigationExtras = { skipLocationChange: false }): Promise<boolean>
    

Navigate based on the provided url. This navigation is always absolute.

Returns a promise that:

  • resolves to 'true' when navigation succeeds,
  • resolves to 'false' when navigation fails,
  • is rejected when an error happens.

Usage

      
      router.navigateByUrl("/team/33/user/11");

// Navigate without updating the URL
router.navigateByUrl("/team/33/user/11", { skipLocationChange: true });
    

In opposite to navigate, navigateByUrl takes a whole URL and does not apply any delta to the current one.


      
      navigate(commands: any[], extras: NavigationExtras = { skipLocationChange: false }): Promise<boolean>
    

Navigate based on the provided array of commands and a starting point. If no starting route is provided, the navigation is absolute.

Returns a promise that:

  • resolves to 'true' when navigation succeeds,
  • resolves to 'false' when navigation fails,
  • is rejected when an error happens.

Usage

      
      router.navigate(['team', 33, 'user', 11], {relativeTo: route});

// Navigate without updating the URL
router.navigate(['team', 33, 'user', 11], {relativeTo: route, skipLocationChange: true});
    

In opposite to navigateByUrl, navigate always takes a delta that is applied to the current URL.


      
      serializeUrl(url: UrlTree): string
    

Serializes a UrlTree into a string


      
      parseUrl(url: string): UrlTree
    

Parses a string into a UrlTree


      
      isActive(url: string | UrlTree, exact: boolean): boolean
    

Returns whether the url is activated