onSameUrlNavigation: 'reload' documentation is misleading about guards, resolvers, and component recreation #70367

Describe the problem that you experienced

Description

The documentation for onSameUrlNavigation is a bit misleading.

It currently states:

'reload' re-runs guards and resolvers and refreshes component instances.

When reading this statement by itself, it seems that setting:

onSameUrlNavigation: 'reload'

will always:

Re-run guards
Re-run resolvers
Recreate the component instance

However, these behaviors are controlled by different router configurations.

For example, whether guards and resolvers run is also affected by runGuardsAndResolvers, while whether a component instance is reused is controlled separately by RouteReuseStrategy.

This can be confusing when a developer expects a CanActivate guard or resolver to run again after navigating to the same URL.

Example

Consider the following route:

{
  path: 'home',
  component: HomeComponent,
  canActivate: [
    () => {
      console.log('CanActivate executed');
      return true;
    }
  ]
}

And the following navigation:

router.navigate(['/home'], {
  onSameUrlNavigation: 'reload'
});

If the application is already at /home, the documentation wording can lead a developer to expect the CanActivate guard to execute again.

However, guard and resolver execution is also affected by the route's runGuardsAndResolvers configuration.
For example, explicitly setting:

{
  path: 'home',
  component: HomeComponent,
  canActivate: [authGuard],
  runGuardsAndResolvers: 'always'
}

makes the intended behavior explicit.

Suggested clarification

It would be clearer if the documentation explained that onSameUrlNavigation and runGuardsAndResolvers control different aspects of the navigation.

For example:

'reload' reprocesses navigation to the current URL. Whether guards and resolvers run again is additionally controlled by the route's runGuardsAndResolvers configuration. Component instance reuse is controlled separately by RouteReuseStrategy.

This would make the relationship between these router configuration options clearer and avoid giving the impression that onSameUrlNavigation: 'reload' alone guarantees that guards, resolvers, and component instances will all be refreshed.

Enter the URL of the topic with the problem

https://angular.dev/guide/routing/customizing-route-behavior#react-to-same-url-navigations

Describe what you were looking for in the documentation

No response

Describe the actions that led you to experience the problem

No response

Describe what you want to experience that would fix the problem

No response

Add a screenshot if that helps illustrate the problem

No response

If this problem caused an exception or error, please paste it here

If the problem is browser-specific, please specify the device, OS, browser, and version

Provide any additional information here in as much as detail as you can