ExtraOptions

interface

Represents options to configure the router.

interface ExtraOptions {
  enableTracing?: boolean
  useHash?: boolean
  initialNavigation?: InitialNavigation
  errorHandler?: ErrorHandler
  preloadingStrategy?: any
  onSameUrlNavigation?: 'reload' | 'ignore'
  scrollPositionRestoration?: 'disabled' | 'enabled' | 'top'
  anchorScrolling?: 'disabled' | 'enabled'
  scrollOffset?: [number, number] | (() => [number, number])
  paramsInheritanceStrategy?: 'emptyOnly' | 'always'
  malformedUriErrorHandler?: (error: URIError, urlSerializer: UrlSerializer, url: string) => UrlTree
  urlUpdateStrategy?: 'deferred' | 'eager'
  relativeLinkResolution?: 'legacy' | 'corrected'
}

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

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.

© 2010–2019 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://v7.angular.io/api/router/ExtraOptions