{ "id": "api/router/ExtraOptions", "title": "ExtraOptions", "contents": "\n\n
\n
\n
\n \n API > @angular/router\n
\n
\n mode_edit\n code\n
\n
\n \n
\n

ExtraOptionslink

\n \n \n \n \n \n
\n \n \n\n
\n \n
\n

A set of configuration options for a router module, provided in the\nforRoot() method.

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

See alsolink

\n
    \n \n

  • forRoot()

    \n
    • \n
\n
\n\n\n \n \n \n
\n

Propertieslink

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
PropertyDescription
\n \n enableTracing?: boolean\n \n \n

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

\n\n \n
\n \n useHash?: boolean\n \n \n

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

\n\n \n
\n \n initialNavigation?: InitialNavigation\n \n \n

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

\n\n \n
\n \n errorHandler?: ErrorHandler\n \n \n

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

\n\n \n
\n \n preloadingStrategy?: any\n \n \n

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

\n\n \n
\n \n onSameUrlNavigation?: 'reload' | 'ignore'\n \n \n

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

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

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

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

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

\n\nclass AppModule {\n constructor(router: Router, viewportScroller: ViewportScroller) {\n router.events.pipe(\n filter((e: Event): e is Scroll => e instanceof Scroll)\n ).subscribe(e => {\n if (e.position) {\n // backward navigation\n viewportScroller.scrollToPosition(e.position);\n } else if (e.anchor) {\n // anchor navigation\n viewportScroller.scrollToAnchor(e.anchor);\n } else {\n // forward navigation\n viewportScroller.scrollToPosition([0, 0]);\n }\n });\n }\n}\n\n\n
\n \n anchorScrolling?: 'disabled' | 'enabled'\n \n \n

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

\n\n

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

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

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

\n\n

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

\n\n
\n \n paramsInheritanceStrategy?: 'emptyOnly' | 'always'\n \n \n

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

\n\n

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

\n

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

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

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

\n\n
    \n
  • 'URIError' - Error thrown when parsing a bad URL.
    • \n
  • 'UrlSerializer' - UrlSerializer that’s configured with the router.
    • \n
  • 'url' - The malformed URL that caused the URIError
    • \n
\n\n
\n \n urlUpdateStrategy?: 'deferred' | 'eager'\n \n \n

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

\n\n \n
\n \n relativeLinkResolution?: 'legacy' | 'corrected'\n \n \n

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

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

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

\n

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

\n

However, this will work:

\n

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

\n

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

\n

The default in v11 is corrected.

\n\n
\n
\n \n\n\n \n\n\n
\n
\n\n\n" }