v1.117.1 Renders Blank Screen Before Pending Component

[Carlwirkus]

Which project does this relate to?

Router

Describe the bug

After upgrading to the latest version of router, I've noticed that there's a screen flash (to an empty screen) before the pending component renders.

The issue seems to be from this PR: https://github.com/TanStack/router/pull/4044/files

Reproduction:
https://github.com/Carlwirkus/router-117.1-bug

The red screen should never appear.

Your Example Website or App

https://github.com/Carlwirkus/router-117.1-bug/blob/main/src/main.tsx

Steps to Reproduce the Bug or Issue

1. npm install
2. npm run dev
3. Observe the loading states:
   • Blue (index.html fallback)
   • Red <-- this is the bug
   • Yellow (pending comonent)
   • Green (route loaded)

Expected behavior

The red screen should never appear (it's a background colour around the RouteProvider). The route provider must be returning null for a period before it renders the pending component. This works on 1.117.0 and is broken in 1.117.1.

Screenshots or Videos

https://www.loom.com/share/9bda2fdbe0ac4e629d41855b5c66c6ac

Platform

• Router 1.117.1

Additional context

No response

[schiller-manuel]

your root route is never pending since it does not have beforeLoad nor a loader.
the index route's pending component is shown after pendingMs, which by default is 1000 ms

https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpendingms-property

if you set defaultPendingMs to 0 (or the index route pendingMs), the fallback will be rendered immediately.

[Carlwirkus]

Screen.Recording.2025-07-25.at.8.54.46.am.mov

Hey!

Sorry I had the defaultPendingComponent set, the one on the root route was a red herring.

    <div className="bg-red-500 h-screen">
      <RouterProvider router={router} defaultPendingMs={0} defaultPendingComponent={() => <div className="bg-yellow-500 h-screen">loading..</div>}  />
    </div>

With a 0ms pending you still see a frame of the red background causing the screen to flash.

I've updated the example for demonstration and attached a video where it's more pronounced.

[Carlwirkus]

if you set defaultPendingMs to 0 (or the index route pendingMs), the fallback will be rendered immediately.

Would this be a sensible default for the root route? Or maybe like an initialComponent?

From what I understand during this period the router isn't suspending so can't display a fallback.

[schiller-manuel]

Would this be a sensible default for the root route?

we probably need to add separate configuration for the initial load, as you might want to have different pendingMs values on subsequent navigations.

[Ridtt]

Would this be a sensible default for the root route?

we probably need to add separate configuration for the initial load, as you might want to have different pendingMs values on subsequent navigations.

Or make it accept a function like shouldReload do 🙂

[schiller-manuel]

and how would you know that is the initial load inside that function?

[Ridtt]

and how would you know that is the initial load inside that function?

Or am I missing something?

[schiller-manuel]

that might work for the root route, but not for other routes. is this only relevant for the root route?

[TeChn4K]

I'm also hitting this issue. To be able to set a separate pendingMs for the initial load would be very helpful as I don't want to set the default to 0 for the whole app.

With a 0ms pending you still see a frame of the red background causing the screen to flash.

Same for me

[codeart1st]

Sitting in the same boat, coming from React Router where hydrateFallbackElement works like a charm to get a smooth transition to the actual content. With @tanstack/router the best you can get is one ugly frame in between.