Skip to content
Source
Sign inSign up
TanStack/router

`blockerFn` in `router.history.block()` returns `true` to block navigation β€” somewhat confusing #3876

Send to my agent
OpenFelixTellmann(GitHub profile, opens in a new tab) opened this issue 1 comment

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

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

  2. schiller-manuel(GitHub profile, opens in a new tab) added labelsdocumentation

Sign in to join this conversation.