Angular 12 References/ Router
πŸ€ Angular References

ExtraOptions interface

Represents options to configure the router.

Example

...
RouterModule.forRoot([
  // Routes definition
], {
  enableTracing: true,
}),

Options

enableTracing#

enableTracing?: boolean

When true, log all internal navigation events to the console. Use for debugging.

useHash#

useHash?: boolean

When true, enable the location strategy that uses the URL fragment instead of the history API.

initialNavigation#

initialNavigation?: InitialNavigation

One of enabled, enabledBlocking, enabledNonBlocking or disabled. When set to enabled or enabledBlocking, the initial navigation starts before the root component is created. The bootstrap is blocked until the initial navigation is complete. This value is required for server-side rendering to work. When set to enabledNonBlocking, the initial navigation starts after the root component has been created. The bootstrap is not blocked on the completion of the initial navigation. When set to disabled, the initial navigation is not performed. The location listener is set up before the root component gets created. Use if there is a reason to have more control over when the router starts its initial navigation due to some complex initialization logic.

errorHandler#

errorHandler?: ErrorHandler

A custom error handler for failed navigations. If the handler returns a value, the navigation Promise is resolved with this value. If the handler throws an exception, the navigation Promise is rejected with the exception.

preloadingStrategy#

preloadingStrategy?: any

Configures a preloading strategy. One of PreloadAllModules or NoPreloading (the default).

onSameUrlNavigation#

onSameUrlNavigation?: 'reload'|'ignore'

Define what the router should do if it receives a navigation request to the current URL. Default is ignore, which causes the router ignores the navigation. This can disable features such as a "refresh" button. Use this option to configure the behavior when navigating to the current URL. Default is 'ignore'.

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'.

scrollPositionRestoration#

scrollPositionRestoration?: 'disabled'|'enabled'|'top'

Configures if the scroll position needs to be restored when navigating back.

  • 'disabled'- (Default) Does nothing. Scroll position is maintained on navigation.
  • 'top'- Sets the scroll position to x = 0, y = 0 on all navigation.
  • 'enabled'- Restores the previous scroll position on backward navigation, else sets the position to the anchor if one is provided, or sets the scroll position to [0, 0] (forward navigation). This option will be the default in the future.

You can implement custom scroll restoration behavior by adapting the enabled behavior as in the following example.

class AppModule {
   constructor(router: Router, viewportScroller: ViewportScroller) {
     router.events.pipe(
       filter((e: Event): e is Scroll => e instanceof Scroll)
     ).subscribe(e => {
       if (e.position) {
         // backward navigation
         viewportScroller.scrollToPosition(e.position);
       } else if (e.anchor) {
         // anchor navigation
         viewportScroller.scrollToAnchor(e.anchor);
       } else {
         // forward navigation
         viewportScroller.scrollToPosition([0, 0]);
       }
     });
   }
}
  • disabled β€” does nothing (default).
  • top β€” set the scroll position to 0,0.
  • enabled β€” set the scroll position to the stored position. This option will be the default in the future.

When enabled, the router stores and restores scroll positions during navigation. When navigating forward, the scroll position will be set to [0, 0], or to the anchor if one is provided.

anchorScrolling#

anchorScrolling?: 'disabled'|'enabled'

When set to 'enabled', scrolls to the anchor element when the URL has a fragment. Anchor scrolling is disabled by default.

Anchor scrolling does not happen on 'popstate'. Instead, we restore the position that we stored or scroll to the top.

  • disabled β€” does nothing (default).
  • enabled β€” scrolls to the element. This option will be the default in the future.

Anchor scrolling does not happen on popstate. Instead, we restore the position that we stored or scroll to the top.

scrollOffset#

scrollOffset?: [number, number]|(() => [number, number])

Configures the scroll offset the router will use when scrolling to an element.

When given a tuple with x and y position value, the router uses that offset each time it scrolls. When given a function, the router invokes the function every time it restores scroll position.

When given a tuple with two numbers, the router will always use the numbers. When given a function, the router will invoke the function every time it restores scroll position.

paramsInheritanceStrategy#

paramsInheritanceStrategy?: 'emptyOnly'|'always'

Defines how the router merges parameters, data, and resolved data from parent to child routes. By default ('emptyOnly'), inherits parent parameters only for path-less or component-less routes.

Set to 'always' to enable unconditional inheritance of parent parameters.

Note that when dealing with matrix parameters, "parent" refers to the parent Route config which does not necessarily mean the "URL segment to the left". When the Route path contains multiple segments, the matrix parameters must appear on the last segment. For example, matrix parameters for {path: 'a/b', component: MyComp} should appear as a/b;foo=bar and not a;foo=bar/b.

Available options are:

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

malformedUriErrorHandler#

malformedUriErrorHandler?: (error: URIError, urlSerializer: UrlSerializer, url: string) => UrlTree

A custom handler for malformed URI errors. The handler is invoked when encodedURI contains invalid character sequences. The default implementation is to redirect to the root URL, dropping any path or parameter information. The function takes three parameters:

  • 'URIError' - Error thrown when parsing a bad URL.
  • 'UrlSerializer' - UrlSerializer that’s configured with the router.
  • 'url' - The malformed URL that caused the URIError

The default implementation is to redirect to the root url dropping any path or param info. This function passes three parameters:

  • URIError β€” Error thrown when parsing a bad URL
  • UrlSerializer β€” UrlSerializer that’s configured with the router.
  • url β€” The malformed URL that caused the URIError.

urlUpdateStrategy#

urlUpdateStrategy?: 'deferred'|'eager'

Defines when the router updates the browser URL. By default ('deferred'), update after successful navigation. Set to 'eager' if prefer to update the URL at the beginning of navigation. Updating the URL early allows you to handle a failure of navigation by showing an error message with the URL that failed.

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#

relativeLinkResolution?: 'legacy'|'corrected'

Enables a bug fix that corrects relative link resolution in components with empty paths. Example:

const routes = [
   {
     path: '',
     component: ContainerComponent,
     children: [
       { path: 'a', component: AComponent },
       { path: 'b', component: BComponent },
     ]
   }
];

From the ContainerComponent, you should be able to navigate to AComponent using the following routerLink, but it will not work if relativeLinkResolution is set to 'legacy':

<a [routerLink]="['./a']">Link to A</a>

However, this will work:

<a [routerLink]="['../a']">Link to A</a>

In other words, you're required to use ../ rather than ./ when the relative link resolution is set to 'legacy'.

The default in v11 is corrected.

The current default in v6 is legacy, and this option will be removed in v7 to default to the corrected behavior.