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 }) => {
return true;
}
});
π 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
can't change the logic without breaking, so docs and types it is. feel free to raise a PR