resetScroll from a navigation is lost when the destination navigates while it is still settling

[daveycodez]

Describe the bug

A navigation's resetScroll intent is stored in a single slot on the router rather than per navigation:

// packages/router-core/src/router.ts
this._scroll.next = next.resetScroll ?? true

If a second navigation is committed while the first is still settling, it overwrites that slot and the first navigation's scroll reset is silently dropped.

This shows up with an ordinary pattern: a page derives state from its own data and writes it back into its URL on first render.

useEffect(() => {
  if (color) return
  navigate({
    to: '/results',
    replace: true,
    resetScroll: false, // correct: this is not a page change
    search: (prev) => ({ ...prev, color: 'w,u,c' }),
  })
}, [color, navigate])

resetScroll: false is correct for that navigation — it only adds a search param to the route you are already on, and it should not move the viewport. But it lands in the same slot as the resetScroll: true recorded by the link navigation that is still settling. That navigation then never resets, and the user is left looking at the new page at the previous page's scroll offset.

Omitting resetScroll: false is not a workaround either: the reset then happens, but under the second navigation's timing, so the destination is painted at the old scroll offset first and visibly jumps to the top afterwards.

The two navigations have independent, explicitly documented resetScroll values, so neither should be able to consume or cancel the other's.

Your Example Website or App

https://github.com/daveycodez/tanstack-router-scroll-repro

Steps to Reproduce the Bug or Issue

1. npm install && npm run dev
2. Scroll to the bottom of the home page
3. Click "open the results page"

Or run the included Playwright test: npx playwright install chromium && npm test

Expected behavior

Following the link resets scroll to the top of the results page.

Actual behavior

Scroll stays at the home page's offset (~8400px). The read-out in the bottom-right corner turns red.

The only variable is resetScroll: false on the second navigation, over 3 runs each:

second navigation	link navigation's reset
resetScroll: false	never applied — stays at 8420
default (true)	applied — 0

Platform

• @tanstack/react-router: 1.170.25
• Browser: Chromium 141
• OS: macOS

Additional context

Found while debugging a search page that infers filters from its results and writes them into the URL after render — the write cannot happen in beforeLoad/SSR there, because the filtered URL must not be the indexed one.

[daveycodez]

Confirming the diagnosis from the app this came from: holding the derived-state write until the router is idle fixes it, which is consistent with the two navigations sharing one _scroll.next slot.

const status = useRouterState({ select: (s) => s.status })

useEffect(() => {
  if (status !== 'idle') return          // don't overlap the incoming navigation
  if (!pendingFill || writtenRef.current === pendingFill) return
  writtenRef.current = pendingFill
  navigate({ replace: true, resetScroll: false, search: (prev) => ({ ...prev, ...pendingFill }) })
}, [pendingFill, navigate, status])

With this, the link navigation's resetScroll: true survives and is applied, the destination renders from the top, and back-navigation restores correctly. Without it, the write lands while the link navigation is still settling and that navigation's reset is never applied.

Two notes for anyone hitting this:

• status in the dependency array means the effect re-runs on the navigation the write itself starts, so the already-written value has to be tracked or it loops.
• Waiting for idle is a workaround, not a fix — it just avoids overlapping navigations. It also delays the URL update until after the page has settled, which is visible if the derived params drive anything on screen.

The underlying issue stands: resetScroll is documented per-navigation, so one navigation's value shouldn't be able to consume or cancel another's.

[daveycodez]

Some notes on where this lives in the source, in case they're useful.

The scroll intent is router-global, not per-navigation.

_scroll is a single mutable slot shared by every navigation. commitLocation writes to it:

// packages/router-core/src/router.ts
this._scroll.next = next.resetScroll ?? true

and _scroll.hash is written the same way in load(). The onRendered handler in scroll-restoration.ts then consumes whatever is in the slot and resets it for the next navigation:

const shouldResetScroll = scroll.next
const hashNavigation = scroll.hash
...
scroll.next = true
scroll.hash = false

Nothing ties the value to the navigation that set it, so a navigation committed while another is still settling overwrites the earlier one's intent.

There is already a precedent for the per-navigation form. The sibling option is stored on the location and read per navigation, in this same handler:

// packages/router-core/src/scroll-restoration.ts
const hashScrollIntoViewOptions =
  event.toLocation.state.__hashScrollIntoViewOptions ?? true

resetScroll could follow exactly that shape: commitLocation writes it onto the location being committed, the handler reads event.toLocation.state.__TSR_resetScroll ?? true, and the reset-after-use goes away because nothing is shared.

[daveycodez]

One thing that per-navigation storage alone would not settle, since it needs a maintainer's call rather than a refactor.

Moving resetScroll onto the location fixes the overwriting, but not this report directly. The commit that actually lands here is the replace's, so its resetScroll: false is still the value read, and the link navigation's reset is still never applied — the user still ends up on the new page at the old page's offset.

So there's a semantic question: when navigation B supersedes an in-flight navigation A whose scroll reset was never applied, what should the resulting commit do?

The rule that seems defensible: a superseding navigation that does not change the pathname is a URL patch rather than a page change, so it should inherit A's pending reset — effectively OR-ing the un-applied intents across the superseded chain. resetScroll: false would then keep meaning "this write must not move the viewport" without also cancelling a real page change that is still in flight.

Whatever rule you pick, the useful property is that resetScroll: false on a same-route search-param write should not be able to swallow a pending reset from a genuine navigation.

[daveycodez]

Separate follow-up, only tangential to the lost-intent problem above but visible in the same flows.

Even when the reset does fire, it is emitted from a continuation that awaits the framework's render acknowledgement:

// packages/router-core/src/load-client.ts
const rendered = await router.startTransition(commit, result[1 /* matches */])
...
router.batch(() => {
  ...
  if (rendered && router._tx === tx) {
    router.emit({ type: 'onRendered', ...changeInfo })
  }
})

That acknowledgement is settled in a layout effect (MatchesInner in packages/react-router/src/Matches.tsx), but the emit happens after the await, so on heavier pages the browser can paint the destination before the scroll handler runs. The symptom is the destination appearing at the previous page's scroll offset for a few frames and then jumping to the top, rather than never being reset at all.

Applying the scroll adjustment from the same layout effect that settles the acknowledgement would make it pre-paint by construction. I measured ~400-700ms of wrong-offset paint on a real app before the reset landed, so it is noticeable on pages whose content arrives after the route commits.

Happy to open this as its own issue if you'd rather keep them apart.