Cookies concent notice

This site uses cookies from Google to deliver its services and to analyze traffic.
Learn more
Skip to main content
This site is no longer updated.Head to Angular.devHome
/

This is the archived documentation for Angular v17. Please visit angular.dev to see this page for the current version of Angular.

Router

A service that provides navigation among views and URL manipulation capabilities.

      
      class Router {
  events: Observable<Event>
  routerState
  errorHandler: (error: any) => any
  navigated: boolean
  routeReuseStrategy: RouteReuseStrategy
  onSameUrlNavigation: OnSameUrlNavigation
  config: Routes
  componentInputBindingEnabled: boolean
  url: string
  lastSuccessfulNavigation: Navigation | null
initialNavigation(): void
setUpLocationChangeListener(): void
getCurrentNavigation(): Navigation | null
resetConfig(config: Routes): void
dispose(): void
createUrlTree(commands: any[], navigationExtras: UrlCreationOptions = {}): UrlTree
navigateByUrl(url: string | UrlTree, extras: NavigationBehaviorOptions = {...}): Promise<boolean>
navigate(commands: any[], extras: NavigationExtras = { skipLocationChange: false }): Promise<boolean>
serializeUrl(url: UrlTree): string
parseUrl(url: string): UrlTree
isActive(url: string | UrlTree, matchOptions: boolean | IsActiveMatchOptions): boolean
isActive(url: string | UrlTree, exact: boolean): boolean
isActive(url: string | UrlTree, matchOptions: IsActiveMatchOptions): boolean
isActive(url: string | UrlTree, matchOptions: boolean | IsActiveMatchOptions): boolean }

See also

Provided in

Properties

Property Description
events: Observable<Event> Read-Only

An event stream for routing events.

routerState Read-Only

The current state of routing in this NgModule.

errorHandler: (error: any) => any

A handler for navigation errors in this NgModule.

Deprecated Subscribe to the Router events and watch for NavigationError instead. provideRouter has the withNavigationErrorHandler feature to make this easier.

See also:

navigated: boolean

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

routeReuseStrategy: RouteReuseStrategy

A strategy for re-using routes.

Deprecated Configure using providers instead: {provide: RouteReuseStrategy, useClass: MyStrategy}.

onSameUrlNavigation: OnSameUrlNavigation

How to handle a navigation request to the current URL.

Deprecated Configure this through provideRouter or RouterModule.forRoot instead.

See also:

config: Routes
componentInputBindingEnabled: boolean Read-Only

Indicates whether the application has opted in to binding Router data to component inputs.

This option is enabled by the withComponentInputBinding feature of provideRouter or bindToComponentInputs in the ExtraOptions of RouterModule.forRoot.

url: string Read-Only

The current URL.

lastSuccessfulNavigation: Navigation | null Read-Only

The Navigation object of the most recent navigation to succeed and null if there has not been a successful navigation yet.

Methods

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

      
      initialNavigation(): void
    
Parameters

There are no parameters.

Returns

void

Sets up the location change listener. This listener detects navigations triggered from outside the Router (the browser back/forward buttons, for example) and schedules a corresponding Router navigation so that the correct events, guards, etc. are triggered.

      
      setUpLocationChangeListener(): void
    
Parameters

There are no parameters.

Returns

void

Returns the current Navigation object when the router is navigating, and null when idle.

      
      getCurrentNavigation(): Navigation | null
    
Parameters

There are no parameters.

Returns

Navigation | null

Resets the route configuration used for navigation and generating links.

      
      resetConfig(config: Routes): void
    
Parameters
config Routes

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 }
 ]}
]);
    

Disposes of the router.

      
      dispose(): void
    
Parameters

There are no parameters.

Returns

void

Appends URL segments to the current URL tree to create a new URL tree.

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

An array of URL fragments with which to construct the new URL tree. If the path is static, can be the literal URL string. For a dynamic path, pass an array of path segments, followed by the parameters for each segment. The fragments are applied to the current URL tree or the one provided in the relativeTo property of the options object, if supplied.

navigationExtras UrlCreationOptions

Options that control the navigation strategy.

Optional. Default is {}.

Returns

UrlTree: The new URL tree.

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});

Note that a value of `null` or `undefined` for `relativeTo` indicates that the
tree should be created relative to the root.
    

Navigates to a view using an absolute route path.

See also:

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

An absolute path for a defined route. The function does not apply any delta to the current URL.

extras NavigationBehaviorOptions

An object containing properties that modify the navigation strategy.

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.

The following calls request navigation to an absolute path.

      
      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.

See also:

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

An array of URL fragments with which to construct the target URL. If the path is static, can be the literal URL string. For a dynamic path, pass an array of path segments, followed by the parameters for each segment. The fragments are applied to the current URL or the one provided in the relativeTo property of the options object, if supplied.

extras NavigationExtras

An options object that determines how the URL should be constructed or interpreted.

Optional. Default is { skipLocationChange: false }.

Returns

Promise<boolean>: A Promise that resolves to true when navigation succeeds, or false when navigation fails. The Promise is rejected when an error occurs if resolveNavigationPromiseOnError is not true.

The following calls request navigation to a dynamic route path relative to the current URL.

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

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

Serializes a UrlTree into a string

      
      serializeUrl(url: UrlTree): string
    
Parameters
url UrlTree
Returns

string

Parses a string into a UrlTree

      
      parseUrl(url: string): UrlTree
    
Parameters
url string
Returns

UrlTree

3 overloads...

Show All Hide All expand_more
Overload #1

Returns whether the url is activated.

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

Deprecated Use IsActiveMatchOptions instead.

  • The equivalent IsActiveMatchOptions for true is {paths: 'exact', queryParams: 'exact', fragment: 'ignored', matrixParams: 'ignored'}.
  • The equivalent for false is {paths: 'subset', queryParams: 'subset', fragment: 'ignored', matrixParams: 'ignored'}.
Parameters
url string | UrlTree
exact boolean
Returns

boolean


Overload #2

Returns whether the url is activated.

      
      isActive(url: string | UrlTree, matchOptions: IsActiveMatchOptions): boolean
    
Parameters
url string | UrlTree
matchOptions IsActiveMatchOptions
Returns

boolean


Overload #3
      
      isActive(url: string | UrlTree, matchOptions: boolean | IsActiveMatchOptions): boolean
    
Parameters
url string | UrlTree
matchOptions boolean | IsActiveMatchOptions
Returns

boolean