pendingComponent animation restarts during hydration of an ssr: false route

[Nandan1996]

Is it expected for an ssr: false route's pending UI to switch to a different DOM instance during initial hydration, while the same loader is still pending?

I have an SSR-enabled parent layout and a child route whose loader runs on the client. The child awaits its data and uses an animated SVG as its pendingComponent. On a direct page load, the indicator appears in the server HTML, then its animation restarts during hydration, before the data arrives.

The relevant configuration, simplified from the application, is:

export const Route = createFileRoute('/_shell/example')({
  ssr: false,
  loader: async () => {
    await new Promise((resolve) => setTimeout(resolve, 2500))
    return { message: 'Loaded' }
  },
  pendingMs: 0,
  pendingMinMs: 0,
  pendingComponent: AnimatedSpinner,
  component: ExamplePage,
})

AnimatedSpinner uses an ordinary repeating CSS animation. The intended behavior is one continuous pending animation until the loader resolves.

In a production-build browser capture, with the data request delayed, DOM-identity tracing showed:

Time after navigation	Pending UI
342 ms	Server-rendered indicator A is visible
1,929 ms	A is hidden; a different indicator B is visible
4,854 ms	Pending indicators are gone; route content is shown

There was one data request. The SSR parent remained visible. More precisely, the first indicator was hidden when the second appeared; it was not immediately removed from the DOM.

Looking at MatchView, the same pending element is supplied to both the outer Suspense boundary and the inner ClientOnly fallback. My understanding is that hydration switches ClientOnly to MatchInner, which suspends on the pending loader, causing the outer boundary to display a new fallback instance. This seems consistent with the observed animation restart.

Is that transition intentional? Could the router preserve the visible pending instance across it, or is there a supported configuration for keeping the animation continuous without implementing a separate loading-state coordinator in the application?

Observed with:

• @tanstack/react-router: 1.170.34
• @tanstack/react-start: 1.168.51
• React / React DOM: 19.3.0
• Vite: 8.0.9
• Chrome on macOS, production build

The source link above is a current upstream snapshot; the runtime observation is from the versions listed. I have not published a standalone reproduction yet, so I am starting this as a discussion about the intended behavior.

[skyzhao1223]

Your reading of MatchView is right, and the detail that indicator A was hidden rather than removed is what pins down the exact path. I traced this on main (ddad69a — Match.tsx there is identical to the fe7f1fd you linked) and reproduced it in jsdom against published @tanstack/react-router 1.170.39 on React 19.3.0, using plain react-router with the same window.$_TSR bootstrap the repo's own hydration tests use.

Here's the chain for an ssr: false route. The server skips the loader outright (load-server.ts resolves it as SKIPPED) and the match dehydrates as { status: 'pending', ssr: false }. While rendering, MatchView computes resolvedNoSsr and wraps MatchInner in <ClientOnly fallback={pendingElement}>, all inside <React.Suspense fallback={pendingElement}>. ClientOnly is a useSyncExternalStore whose getServerSnapshot returns false, so the server HTML contains your spinner — that's the documented "Fallback Rendering" behavior in the Selective SSR guide, not an accident.

Hydration matches, so node A survives. Then the store snapshot flips, ClientOnly re-renders to its children, and MatchInner sees match.status === 'pending' and does throw router._tx[5]. _tx is the active LoadTransaction; slot 5 is its done promise — the whole client load's completion, not your loader alone. The route's own Suspense boundary catches it, and React does what it always does when a mounted boundary re-suspends: it hides the committed children (display: none, which is why A stayed in the DOM) and mounts the fallback fresh. That fallback is node B. It's even the same element object as A's — MatchView computes pendingElement once and passes it to both slots — but element identity doesn't carry an instance across tree positions. The fallback slot is a brand-new mount, and a brand-new <svg> starts its animation timeline at zero. When the transaction settles, the boundary re-renders with status: 'success' and A is finally unmounted. My repro walked all three states: spinner in the server HTML; after the flip with the loader still pending, A connected but display:none and a distinct visible B; content shown and both spinners gone after resolve.

So the transition is structural, and nothing in the router tries to preserve the DOM instance across it — with pending UI living in two tree positions, React couldn't reuse the node anyway. Both instances are intended; that the second one is a fresh mount is a consequence nobody has designed around. Worth knowing: this area is actively being reworked. Issue #8180 (a Suspense boundary invalidated before it finishes hydrating, React error #421) has an open PR, #8185, moving the match-store subscription below the ClientOnly gate. That fixes a different symptom and doesn't change the fallback swap, and I couldn't find an existing issue tracking the restart itself.

What you can do without building a loading-state coordinator:

The cleanest option uses a hook the router already exports. useHydrated() is false during SSR and the first hydration pass, true afterwards:

function AnimatedSpinner() {
  const hydrated = useHydrated()
  if (!hydrated) return <SpinnerFrame0 /> // same SVG, no animation — goes into server HTML
  return <SpinnerAnimated />
}

The animated element then mounts exactly once (as node B), so there is nothing running to restart — the placeholder just starts moving. I ran this variant through the same harness: static markup in the server HTML, the animated instance visible after the flip.

If you want motion from first paint, make the restart invisible instead: keep a module-scope start timestamp and give each mount a negative offset, style={{ animationDelay: -${(Date.now() - start) % DURATION}ms }}. A negative animation-delay drops an element into its cycle partway through (plain CSS behavior, not a router feature), so B picks up visually where A was. Two lines, and it's robust against any future remount.

Things that won't help, some of them tempting:

• pendingMs / pendingMinMs only time when pending UI shows and how long it lingers; the hydration handoff deliberately preserves the pending presentation without re-delaying it (offerPending in load-client.ts). Your 0/0 is already the tightest setting.
• ssr: 'data-only' goes through the same machinery — resolvedNoSsr covers both, and the handoff presents a data-only boundary as pending too.
• wrapInSuspense: false. On the initial hydration it does keep your server spinner alive — the throw now reaches the root's still-dehydrated boundary, and React keeps showing the server HTML until the transaction resolves. But on client-side navigation the same throw suspends the root Outlet's boundary, whose fallback is your defaultPendingComponent or nothing at all: your route's pendingComponent never renders and the whole layout area stays hidden until the loader resolves. I reproduced that too; I'd stay away.
• If your loader can run on the server, dropping ssr: false makes the problem disappear entirely — the data dehydrates as success, hydration renders content directly, and the pending UI never enters the picture. That's a semantics change only you can judge, but it's the zero-workaround fix.

If you want the router itself to preserve the instance across the swap, that's a structural change (one pending slot instead of two, or a boundary arrangement where the fallback survives) — #8185 is a reasonable place to raise it, or a fresh issue, since nothing tracks it today.