RouterModule

ngmodule

Adds router directives and providers.

See more...

class RouterModule {
  static forRoot(routes: Route[], config?: ExtraOptions): ModuleWithProviders<RouterModule>
  static forChild(routes: Route[]): ModuleWithProviders<RouterModule>
}

Description

Managing state transitions is one of the hardest parts of building applications. This is especially true on the web, where you also need to ensure that the state is reflected in the URL. In addition, we often want to split applications into multiple bundles and load them on demand. Doing this transparently is not trivial.

The Angular router solves these problems. Using the router, you can declaratively specify application states, manage state transitions while taking care of the URL, and load bundles on demand.

Read this developer guide to get an overview of how the router should be used.

Static methods

forRoot()

Creates a module with all the router providers and directives. It also optionally sets up an application listener to perform an initial navigation.

static forRoot(routes: Route[], config?: ExtraOptions): ModuleWithProviders<RouterModule>

Parameters
routes Route[]
config ExtraOptions

Optional. Default is undefined.
Returns

ModuleWithProviders<RouterModule>

Configuration Options:

  • enableTracing Toggles whether the router should log all navigation events to the console.
  • useHash Enables the location strategy that uses the URL fragment instead of the history API.
  • initialNavigation Disables the initial navigation.
  • errorHandler Defines a custom error handler for failed navigations.
  • preloadingStrategy Configures a preloading strategy. See PreloadAllModules.
  • onSameUrlNavigation Define what the router should do if it receives a navigation request to the current URL.
  • scrollPositionRestoration Configures if the scroll position needs to be restored when navigating back.
  • anchorScrolling Configures if the router should scroll to the element when the url has a fragment.
  • scrollOffset Configures the scroll offset the router will use when scrolling to an element.
  • paramsInheritanceStrategy Defines how the router merges params, data and resolved data from parent to child routes.
  • malformedUriErrorHandler Defines a custom malformed uri error handler function. This handler is invoked when encodedURI contains invalid character sequences.
  • urlUpdateStrategy Defines when the router updates the browser URL. The default behavior is to update after successful navigation.
  • relativeLinkResolution Enables the correct relative link resolution in components with empty paths.

See ExtraOptions for more details about the above options.
forChild()

Creates a module with all the router directives and a provider registering routes.

static forChild(routes: Route[]): ModuleWithProviders<RouterModule>

Parameters
routes Route[]
Returns

ModuleWithProviders<RouterModule>

Directives

Name Description 
RouterLink

Lets you link to specific routes in your app.

 
RouterLinkActive

Lets you add a CSS class to an element when the link's route becomes active.

 
RouterLinkWithHref

Lets you link to specific routes in your app.

 
RouterOutlet

Acts as a placeholder that Angular dynamically fills based on the current router state.

Usage notes

RouterModule can be imported multiple times: once per lazily-loaded bundle. Since the router deals with a global shared resource--location, we cannot have more than one router service active.

That is why there are two ways to create the module: RouterModule.forRoot and RouterModule.forChild.

  • forRoot creates a module that contains all the directives, the given routes, and the router service itself.
  • forChild creates a module that contains all the directives and the given routes, but does not include the router service.

When registered at the root, the module should be used as follows

@NgModule({
  imports: [RouterModule.forRoot(ROUTES)]
})
class MyNgModule {}

For submodules and lazy loaded submodules the module should be used as follows:

@NgModule({
  imports: [RouterModule.forChild(ROUTES)]
})
class MyNgModule {}

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