blockerFn in router.history.block() returns true to block navigation — somewhat confusing

[FelixTellmann]

Which project does this relate to?

Router

Describe the bug

Hi TanStack team 👋

While using router.history.block() in TanStack Router v1 (via @tanstack/start), I ran into some confusing behavior:

• I expected blockerFn to behave like typical navigation guards (e.g., return false to block navigation).
• But in TanStack, it actually works the opposite way:
  • return true → blocks navigation
  • return false → allows navigation

This is quite unexpected — especially coming from the legacy React Router v6 unstable_blocker API, other router libraries, or even browser APIs like window.onbeforeunload, where returning false or a blocking signal typically prevents navigation.

---

Repro:

router.history.block({
  blockerFn: ({ nextLocation }) => {
    // show a modal, etc...
    return true; // this blocks navigation (unexpected)
  }
});

🔍 Additionally, this behavior appears to contradict the type signature:

```ts
export type BlockerFn = (args: BlockerFnArgs) => Promise<ShouldAllowNavigation> | ShouldAllowNavigation;

The name ShouldAllowNavigation strongly implies:

true → should allow navigation
false → should block it

But the actual behavior is inverted:
true → blocks navigation
false → allows navigation

Thanks so much — love the work you’re doing on TanStack 🙌
This router is really powerful and shaping up to be the future of routing in React.

** Versions**

    "@tanstack/react-router-with-query": "^1.114.29",
    "@tanstack/react-router": "^1.114.29",
    "@tanstack/react-router-devtools": "^1.114.29",
    "@tanstack/react-start": "^1.114.29",

Your Example Website or App

N/A

Steps to Reproduce the Bug or Issue

N/A

Expected behavior

Suggestions:

• Clarify this behavior in the documentation
• Consider flipping the logic to align with the name and wider conventions
• Alternatively, rename the type to something like ShouldBlockNavigation if the current behavior is intentional

Screenshots or Videos

No response

Platform

** Versions**

    "@tanstack/react-router-with-query": "^1.114.29",
    "@tanstack/react-router": "^1.114.29",
    "@tanstack/react-router-devtools": "^1.114.29",
    "@tanstack/react-start": "^1.114.29",

Additional context

No response

[schiller-manuel]

can't change the logic without breaking, so docs and types it is. feel free to raise a PR