Help Angular by taking a 1 minute survey!Go to surveyHome
API > @angular/router

Router

An NgModule that provides navigation and URL manipulation capabilities.

class Router { constructor(rootComponentType: Type<any>, urlSerializer: UrlSerializer, rootContexts: ChildrenOutletContexts, location: Location, injector: Injector, loader: NgModuleFactoryLoader, compiler: Compiler, config: Route[]) events: Observable<Event> routerState: RouterState errorHandler: ErrorHandler malformedUriErrorHandler: (error: URIError, urlSerializer: UrlSerializer, url: string) => UrlTree navigated: boolean urlHandlingStrategy: UrlHandlingStrategy routeReuseStrategy: RouteReuseStrategy onSameUrlNavigation: 'reload' | 'ignore' paramsInheritanceStrategy: 'emptyOnly' | 'always' urlUpdateStrategy: 'deferred' | 'eager' relativeLinkResolution: 'legacy' | 'corrected' config: Routes url: string initialNavigation(): void setUpLocationChangeListener(): void getCurrentNavigation(): Navigation | null resetConfig(config: Route[]): 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 } 
      
      class Router {
  constructor(rootComponentType: Type<any>, urlSerializer: UrlSerializer, rootContexts: ChildrenOutletContexts, location: Location, injector: Injector, loader: NgModuleFactoryLoader, compiler: Compiler, config: Route[])
  events: Observable<Event>
  routerState: RouterState
  errorHandler: ErrorHandler
  malformedUriErrorHandler: (error: URIError, urlSerializer: UrlSerializer, url: string) => UrlTree
  navigated: boolean
  urlHandlingStrategy: UrlHandlingStrategy
  routeReuseStrategy: RouteReuseStrategy
  onSameUrlNavigation: 'reload' | 'ignore'
  paramsInheritanceStrategy: 'emptyOnly' | 'always'
  urlUpdateStrategy: 'deferred' | 'eager'
  relativeLinkResolution: 'legacy' | 'corrected'
  config: Routes
  url: string
  initialNavigation(): void
  setUpLocationChangeListener(): void
  getCurrentNavigation(): Navigation | null
  resetConfig(config: Route[]): 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
}

See also

Constructor

Creates the router service.
constructor(rootComponentType: Type<any>, urlSerializer: UrlSerializer, rootContexts: ChildrenOutletContexts, location: Location, injector: Injector, loader: NgModuleFactoryLoader, compiler: Compiler, config: Route[])
      
      constructor(rootComponentType: Type<any>, urlSerializer: UrlSerializer, rootContexts: ChildrenOutletContexts, location: Location, injector: Injector, loader: NgModuleFactoryLoader, compiler: Compiler, config: Route[])
Parameters
rootComponentType Type
urlSerializer UrlSerializer
rootContexts ChildrenOutletContexts
location Location
injector Injector
loader NgModuleFactoryLoader
compiler Compiler
config Route[]

Properties

Property Description
events: Observable<Event> Read-only.

An event stream for routing events in this NgModule.
routerState: RouterState Read-only.

The current state of routing in this NgModule.
errorHandler: ErrorHandler

A handler for navigation errors in this NgModule.
malformedUriErrorHandler: (error: URIError, urlSerializer: UrlSerializer, url: string) => UrlTree

Malformed uri error handler is invoked when Router.parseUrl(url) throws an error due to containing an invalid character. The most common case would be a % sign that's not encoded and is not part of a percent encoded sequence.
navigated: boolean

True if at least one navigation event has occurred, false otherwise.
urlHandlingStrategy: UrlHandlingStrategy

Extracts and merges URLs. Used for AngularJS to Angular migrations.
routeReuseStrategy: RouteReuseStrategy

The strategy for re-using routes.
onSameUrlNavigation: 'reload' | 'ignore'

How to handle a navigation request to the current URL. One of:

  • 'ignore' : The router ignores the request.
  • 'reload' : The router reloads the URL. Use to implement a "refresh" feature.
paramsInheritanceStrategy: 'emptyOnly' | 'always'

How to merge parameters, data, and resolved data from parent to child routes. One of:

  • 'emptyOnly' : Inherit parent parameters, data, and resolved data for path-less or component-less routes.
  • 'always' : Inherit parent parameters, data, and resolved data for all child routes.
urlUpdateStrategy: 'deferred' | 'eager'

Defines when the router updates the browser URL. The default behavior is to update after successful navigation. However, some applications may prefer a mode where the URL gets updated at the beginning of navigation. The most common use case would be updating the URL early so if navigation fails, you can show an error message with the URL that failed. Available options are:

  • 'deferred', the default, updates the browser URL after navigation has finished.
  • 'eager', updates browser URL at the beginning of navigation.
relativeLinkResolution: 'legacy' | 'corrected'

See RouterModule for more information.
config: Routes Declared in constructor.
url: string Read-only.

The current URL.

Methods

initialNavigation()

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

 
      
      initialNavigation(): void
Parameters

There are no parameters.

Returns

void

setUpLocationChangeListener()

Sets up the location change listener.
setUpLocationChangeListener(): void
      
      setUpLocationChangeListener(): void
Parameters

There are no parameters.

Returns

void

getCurrentNavigation()

The current Navigation object if one exists
getCurrentNavigation(): Navigation | null
      
      getCurrentNavigation(): Navigation | null
Parameters

There are no parameters.

Returns

Navigation | null

resetConfig()

Resets the configuration used for navigation and generating links.
resetConfig(config: Route[]): void
      
      resetConfig(config: Route[]): void
Parameters
config Route[]

The route array for the new configuration.
Returns

void

Usage Notes

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

ngOnDestroy()

ngOnDestroy(): void
      
      ngOnDestroy(): void
Parameters

There are no parameters.

Returns

void

dispose()

Disposes of the router.
dispose(): void
      
      dispose(): void
Parameters

There are no parameters.

Returns

void

createUrlTree()

Applies an array of commands to the current URL tree and creates a new URL tree.
createUrlTree(commands: any[], navigationExtras: NavigationExtras = {}): UrlTree
      
      createUrlTree(commands: any[], navigationExtras: NavigationExtras = {}): UrlTree
Parameters
commands any[]

An array of commands to apply.
navigationExtras NavigationExtras

Optional. Default is {}.
Returns

UrlTree: The 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 Notes

// 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}); 
      
      
  1. // create /team/33/user/11
  2. router.createUrlTree(['/team', 33, 'user', 11]);
  3.  
  4. // create /team/33;expand=true/user/11
  5. router.createUrlTree(['/team', 33, {expand: true}, 'user', 11]);
  6.  
  7. // you can collapse static segments like this (this works only with the first passed-in value):
  8. router.createUrlTree(['/team/33/user', userId]);
  9.  
  10. // If the first segment can contain slashes, and you do not want the router to split it, you
  11. // can do the following:
  12.  
  13. router.createUrlTree([{segmentPath: '/one/two'}]);
  14.  
  15. // create /team/33/(user/11//right:chat)
  16. router.createUrlTree(['/team', 33, {outlets: {primary: 'user/11', right: 'chat'}}]);
  17.  
  18. // remove the right secondary node
  19. router.createUrlTree(['/team', 33, {outlets: {primary: 'user/11', right: null}}]);
  20.  
  21. // assuming the current url is `/team/33/user/11` and the route points to `user/11`
  22.  
  23. // navigate to /team/33/user/11/details
  24. router.createUrlTree(['details'], {relativeTo: route});
  25.  
  26. // navigate to /team/33/user/22
  27. router.createUrlTree(['../22'], {relativeTo: route});
  28.  
  29. // navigate to /team/44/user/22
  30. router.createUrlTree(['../../team/44/user/22'], {relativeTo: route});

Navigate based on the provided URL, which must be absolute.
navigateByUrl(url: string | UrlTree, extras: NavigationExtras = { skipLocationChange: false }): Promise<boolean>
      
      navigateByUrl(url: string | UrlTree, extras: NavigationExtras = { skipLocationChange: false }): Promise<boolean>
Parameters
url string | UrlTree

An absolute URL. The function does not apply any delta to the current URL.
extras NavigationExtras

An object containing properties that modify the navigation strategy. The function ignores any properties in the NavigationExtras that would change the provided URL.

Optional. Default is { skipLocationChange: false }.
Returns

Promise<boolean>: A Promise that resolves to 'true' when navigation succeeds, to 'false' when navigation fails, or is rejected on error.
Example
router.navigateByUrl("/team/33/user/11"); // Navigate without updating the URL router.navigateByUrl("/team/33/user/11", { skipLocationChange: true }); 
      
      router.navigateByUrl("/team/33/user/11");

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

Navigate based on the provided array of commands and a starting point. If no starting route is provided, the navigation is absolute.
navigate(commands: any[], extras: NavigationExtras = { skipLocationChange: false }): Promise<boolean>
      
      navigate(commands: any[], extras: NavigationExtras = { skipLocationChange: false }): Promise<boolean>
Parameters
commands any[]
extras NavigationExtras

Optional. Default is { skipLocationChange: false }.
Returns

Promise<boolean>

Returns a promise that:

  • resolves to 'true' when navigation succeeds,
  • resolves to 'false' when navigation fails,
  • is rejected when an error happens.
Example
router.navigate(['team', 33, 'user', 11], {relativeTo: route}); // Navigate without updating the URL router.navigate(['team', 33, 'user', 11], {relativeTo: route, skipLocationChange: true}); 
      
      router.navigate(['team', 33, 'user', 11], {relativeTo: route});

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

The first parameter of navigate() is a delta to be applied to the current URL or the one provided in the relativeTo property of the second parameter (the NavigationExtras).

In order to affect this browser's history.state entry, the state parameter can be passed. This must be an object because the router will add the navigationId property to this object before creating the new history item.

serializeUrl()

Serializes a UrlTree into a string
serializeUrl(url: UrlTree): string
      
      serializeUrl(url: UrlTree): string
Parameters
url UrlTree
Returns

string

parseUrl()

Parses a string into a UrlTree
parseUrl(url: string): UrlTree
      
      parseUrl(url: string): UrlTree
Parameters
url string
Returns

UrlTree

isActive()

Returns whether the url is activated
isActive(url: string | UrlTree, exact: boolean): boolean
      
      isActive(url: string | UrlTree, exact: boolean): boolean
Parameters
url string | UrlTree
exact boolean
Returns

boolean