Help Angular by taking a 1 minute survey!Go to surveyHome

ExtraOptions

Represents options to configure the router.

      
      
  1. interface ExtraOptions {
  2. enableTracing?: boolean
  3. useHash?: boolean
  4. initialNavigation?: InitialNavigation
  5. errorHandler?: ErrorHandler
  6. preloadingStrategy?: any
  7. onSameUrlNavigation?: 'reload' | 'ignore'
  8. scrollPositionRestoration?: 'disabled' | 'enabled' | 'top'
  9. anchorScrolling?: 'disabled' | 'enabled'
  10. scrollOffset?: [number, number] | (() => [number, number])
  11. paramsInheritanceStrategy?: 'emptyOnly' | 'always'
  12. malformedUriErrorHandler?: (error: URIError, urlSerializer: UrlSerializer, url: string) => UrlTree
  13. urlUpdateStrategy?: 'deferred' | 'eager'
  14. relativeLinkResolution?: 'legacy' | 'corrected'
  15. }

Properties

Property Description
enableTracing?: boolean

Makes the router log all its internal events to the console.

useHash?: boolean

Enables the location strategy that uses the URL fragment instead of the history API.

initialNavigation?: InitialNavigation

Disables the initial navigation.

errorHandler?: ErrorHandler

A custom error handler.

preloadingStrategy?: any

Configures a preloading strategy. See PreloadAllModules.

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

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

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

  • 'disabled'--does nothing (default). Scroll position will be maintained on navigation.
  • 'top'--set 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 follows:

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]); } }); } }
      
      
  1. class AppModule {
  2. constructor(router: Router, viewportScroller: ViewportScroller) {
  3. router.events.pipe(
  4. filter((e: Event): e is Scroll => e instanceof Scroll)
  5. ).subscribe(e => {
  6. if (e.position) {
  7. // backward navigation
  8. viewportScroller.scrollToPosition(e.position);
  9. } else if (e.anchor) {
  10. // anchor navigation
  11. viewportScroller.scrollToAnchor(e.anchor);
  12. } else {
  13. // forward navigation
  14. viewportScroller.scrollToPosition([0, 0]);
  15. }
  16. });
  17. }
  18. }
anchorScrolling?: 'disabled' | 'enabled'

Configures if the router should scroll to the element when the url has a fragment.

  • '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?: [number, number] | (() => [number, number])

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

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?: '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.
malformedUriErrorHandler?: (error: URIError, urlSerializer: UrlSerializer, url: string) => UrlTree

A custom malformed uri error handler function. This handler is invoked when encodedURI contains invalid character sequences. 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?: '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'

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 }, ] } ];
      
      const routes = [
  {
    path: '',
    component: ContainerComponent,
    children: [
      { path: 'a', component: AComponent },
      { path: 'b', component: BComponent },
    ]
  }
];
    

From the ContainerComponent, this will not work:

<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 ./. This is currently the default behavior. Setting this option to corrected enables the fix.