This is the archived documentation for Angular v6. Please visit angular.io to see documentation for the current version of Angular.

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

You can implement custom scroll restoration behavior as follows.

class AppModule { constructor(router: Router, viewportScroller: ViewportScroller, store: Store<AppState>) { router.events.pipe(filter(e => e instanceof Scroll), switchMap(e => { return store.pipe(first(), timeout(200), map(() => e)); }).subscribe(e => { if (e.position) { viewportScroller.scrollToPosition(e.position); } else if (e.anchor) { viewportScroller.scrollToAnchor(e.anchor); } else { viewportScroller.scrollToPosition([0, 0]); } }); } }
      
      
  1. class AppModule {
  2. constructor(router: Router, viewportScroller: ViewportScroller, store: Store<AppState>) {
  3. router.events.pipe(filter(e => e instanceof Scroll), switchMap(e => {
  4. return store.pipe(first(), timeout(200), map(() => e));
  5. }).subscribe(e => {
  6. if (e.position) {
  7. viewportScroller.scrollToPosition(e.position);
  8. } else if (e.anchor) {
  9. viewportScroller.scrollToAnchor(e.anchor);
  10. } else {
  11. viewportScroller.scrollToPosition([0, 0]);
  12. }
  13. });
  14. }
  15. }

You can also implement component-specific scrolling like this:

class ListComponent { list: any[]; constructor(router: Router, viewportScroller: ViewportScroller, fetcher: ListFetcher) { const scrollEvents = router.events.filter(e => e instanceof Scroll); listFetcher.fetch().pipe(withLatestFrom(scrollEvents)).subscribe(([list, e]) => { this.list = list; if (e.position) { viewportScroller.scrollToPosition(e.position); } else { viewportScroller.scrollToPosition([0, 0]); } }); } }
      
      
  1. class ListComponent {
  2. list: any[];
  3. constructor(router: Router, viewportScroller: ViewportScroller, fetcher: ListFetcher) {
  4. const scrollEvents = router.events.filter(e => e instanceof Scroll);
  5. listFetcher.fetch().pipe(withLatestFrom(scrollEvents)).subscribe(([list, e]) => {
  6. this.list = list;
  7. if (e.position) {
  8. viewportScroller.scrollToPosition(e.position);
  9. } else {
  10. viewportScroller.scrollToPosition([0, 0]);
  11. }
  12. });
  13. }
  14. }
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 ./. The current default in v6 is legacy, and this option will be removed in v7 to default to the corrected behavior.