❓ How to prevent blank page flash during initial router mount? (with solution)

[jitesh-speakap]

The Problem I Encountered

I'm using TanStack Router with beforeLoad for authentication and data fetching, but I'm experiencing a blank page flash during initial app load. The sequence is:

1. ✅ Initial HTML loads with loader
2. ❌ Brief blank page flash
3. ✅ Router's pendingComponent shows during beforeLoad
4. ✅ Final component renders

What I Tried First

I thought defaultPendingComponent would solve this:

const router = createRouter({
  routeTree,
  defaultPendingComponent: AppLoader,
  context: {
    // my context
  },
  // ... other config
});

But I still got the blank page flash.

Root Cause Analysis

After digging into the source code, I found the issue occurs in the MatchesInner component:

// From @tanstack/react-router/dist/esm/Matches.js
function MatchesInner() {
  const matchId = useRouterState({
    select: (s) => s.matches[0]?.id  // Initially undefined
  });
  
  return (
    <matchContext.Provider value={matchId}>
      <CatchBoundary>
        {matchId ? <Match matchId /> : null}  // ← Renders null = blank page
      </CatchBoundary>
    </matchContext.Provider>
  );
}

The lifecycle gap:

1. RouterProvider mounts → MatchesInner renders null
2. Transitioner calls router.load() in useLayoutEffect (next tick)
3. Only then does loading state activate

My Solution

I implemented a router state-based loading wrapper:

function RootProviders() {
  const [showFallback, setShowFallback] = useState(true);
  
  useEffect(() => {
    const unsubscribe = router.subscribe('onLoad', () => {
      setShowFallback(false);
    });
    return unsubscribe;
  }, []);

  return (
    <>
      {showFallback && <AppLoader />}
      <RouterProvider router={router} />
    </>
  );
}

export default RootProviders;

This completely eliminates the blank page flash! 🎉

My Questions

1. Is there a built-in way to handle this that I missed?

2. Is my solution the recommended approach, or is there a better pattern?

3. Should TanStack Router handle this internally? It seems like a common UX issue for apps with async beforeLoad operations.

4. Would a defaultMountingComponent option make sense for the router to show during this pre-loading state?

Context

This affects any app using:

• Authentication checks in beforeLoad
• Data prefetching in beforeLoad
• Context setup in beforeLoad

My setup:

export const Route = createRootRouteWithContext<GlobalContext>()({
  beforeLoad: async ({ context }) => {
    // Auth validation + data fetching and returns the context
  },
  pendingComponent: AppLoader,
  component: HomeLayout,
});

Reproduction

The issue is reproducible with any app that has async beforeLoad operations. The blank page is brief but noticeable.
Here's a short recording to help you understand:

Screen.Recording.2025-07-01.at.14.19.27.mp4