feat(router-core,history): Global blocking status & proceed/reset actions

[nizans]

This PR introduces a global “blocker” state in and the callbacks needed to continue (proceed) or cancel (reset) a blocked navigation globally, to be consumed directly from the router state.
This enables controlling the blocking status out side the context of the useBlocker that was used to initiate the block.

The per-route useBlocker API remains unchanged—it now also updates the router-level state.

Discussed previously here.

---

This change adds BLOCK and DISMISS-BLOCK actions to the history notify function.
where the BLOCK action holds a ref to the current awaited promise resolver thats currently blocking the navigation, which is then consumed through the router state.

---

Why?

I needed a single, root-level modal that appears whenever any navigation is blocked (unsaved changes, etc.), instead of re-instantiating the modal wherever useBlocker is used.
I expected the router to expose some global blocking state, this PR attempts to provide this functionality.

A short example of the usage:

// Some component in some route
const SomeComponentAnywhere = () => {
  useBlocker({
    shouldBlockFn: () => true,
    withResolver: true,
  })
  
  return <div>something</div>
}

// Simple wrapper for consuming the blocking state
const useBlocking = () =>
  useRouterState({
    select: (state) => state.blocker,
  })

// Another component in some other route
const DifferentComponenetAnywhere = () => {
  const { proceed, reset, status } = useBlocking()

  return (
    <div>
      <span>The global blocking status: {status}</span>
      <button onClick={proceed}>Proceed the blocked navigation</button>
      <button onClick={reset}>Reset the blocked navigation</button>
    </div>
  )
}

A runnable demo is available in examples/global-blocking-state.

Any feedback is appreciated!

[Sheraff]

Could you give a quick explanation for the switch from promises to async generators? I only quickly read the code, so maybe it should be obvious and I didn't see it.

[nizans]

Could you give a quick explanation for the switch from promises to async generators? I only quickly read the code, so maybe it should be obvious and I didn't see it.

Hi @Sheraff

The original blockerFn only lets the history "know" only after the blocking state is already resolved — meaning the navigation is no longer blocked (e.g. the user clicked the "dismiss" button).

To support global blocking state and functionality, there needs to be a blocking step in between, where the navigation is paused but not yet resolved.

To allow "history" to fire some kind of block events — and expose the ability to resolve that same awaited promise globally (i.e. provide the dismiss / proceed callbacks) — I needed a way to pass the resolver to the history layer as soon as the blocking starts.

There might be other ways to approach this, but I found async generators to be an effective solution for this case.

[nlynzaad]

@nizans thank you for this. looking at the discord discussion, it seems there are an item or two that you still want to add on to this PR, maybe we should mark this as draft until those have been added in?

[nizans]

Thanks @nlynzaad

I’ve just pushed a commit that adds the proceedAll functionality that was discussed on Discord, so I believe this PR is good to go and ready for further review.

Quick explanation:
The proceedAll function is exposed through the global blocking state and allows proceeding all active blockers when multiple blockers are blocking navigation. This functionality is only available via the newly added global blocking state.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit e8c83b3

---

☁️ Nx Cloud last updated this comment at 2025-07-31 14:53:07 UTC