Pull-to-refresh on a Suspense infinite feed flashes the whole skeleton

The scenario

A news feed uses useSuspenseInfiniteQuery behind <Suspense fallback={<FeedSkeleton />}>. First paint: skeleton → feed. Good. A "Refresh" button calls queryClient.invalidateQueries({ queryKey: ['feed'] }) (or refetchQueries). Because the update suspends again without a transition, React hides the existing feed and shows the skeleton for the whole refetch — including when 40 items were already on screen. Users call it "the app blinks."

Worse: after a network error, ErrorBoundary shows Retry; Retry only remounts the boundary. Query still has the error cached → immediate rethrow → Retry appears broken until a full reload. Missing QueryErrorResetBoundary.

Why it escaped QA: refresh tested on empty/slow first load (skeleton expected); error retry clicked once after DevTools "clear cache"; transitions never mentioned in the Suspense+Query copy-paste.

Walkthrough

Stage 1 — Name it: Suspense updates need transitions

The transition interplay: suspending updates default to showing the fallback. Wrap the refresh in startTransition so React holds the previous UI and surfaces pending instead. Initial mount still uses the skeleton — correct.

Stage 2 — Reject "just use non-Suspense infinite"

You can — useInfiniteQuery + local isPending — but then you lose the declarative boundary loading model. The bug is the refresh path, not Suspense itself.

Stage 3 — Suspense infinite + transition refresh + error reset

import { Suspense, useTransition } from "react";import { useSuspenseInfiniteQuery, useQueryClient, QueryErrorResetBoundary } from "@tanstack/react-query";import { ErrorBoundary } from "react-error-boundary";
function FeedList() {  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useSuspenseInfiniteQuery({    queryKey: ["feed", "home"],    queryFn: fetchFeedPage,    initialPageParam: 1,    getNextPageParam: (last, all) => (last.length === 0 ? undefined : all.length + 1),    maxPages: 3,  });
  return (    <>      {data.pages.flat().map((item) => (        <FeedCard key={item.id} item={item} />      ))}      {hasNextPage && (        <button type="button" disabled={isFetchingNextPage} onClick={() => void fetchNextPage()}>          {isFetchingNextPage ? "Loading…" : "More"}        </button>      )}    </>  );}
function RefreshButton() {  const qc = useQueryClient();  const [isPending, startTransition] = useTransition();
  return (    <button      type="button"      disabled={isPending}      onClick={() => {        startTransition(() => {          void qc.refetchQueries({ queryKey: ["feed", "home"] });        });      }}    >      {isPending ? "Refreshing…" : "Refresh"}    </button>  );}
export function FeedPage() {  return (    <QueryErrorResetBoundary>      {({ reset }) => (        <ErrorBoundary          onReset={reset}          fallbackRender={({ resetErrorBoundary, error }) => (            <div role="alert">              <p>{error.message}</p>              <button type="button" onClick={resetErrorBoundary}>                Retry              </button>            </div>          )}        >          <RefreshButton />          <Suspense fallback={<FeedSkeleton />}>            <FeedList />          </Suspense>        </ErrorBoundary>      )}    </QueryErrorResetBoundary>  );}

Note: wire onReset={reset} from QueryErrorResetBoundary so Retry clears Query's error state (article Suspense block).

Stage 4 — Harden + verify the loop

• fetchNextPage should not blank the list — isFetchingNextPage is local; don't put next-page fetches in a transition that remounts the boundary incorrectly.
• Prefer refetchQueries in a transition over resetQueries if you want to keep showing data.

Verify the loop. Load feed → Refresh: skeleton does not replace the list; pending on the button. Throttle offline → error UI → Retry: one new GET, feed returns. Without reset wiring: Retry loops the error (reproduce once to confirm the bug).

Variations

1. Pull-to-refresh library — call the same startTransition + refetch.
2. invalidateQueries in transition — same hold behavior.
3. Granular Suspense per section — refresh one column without blanking the chrome.
4. Non-Suspense infinite — if the team won't adopt transitions yet.
5. Router loader + dehydrate — first paint without client suspend; refresh still needs the transition discipline.

Trade-offs and common pitfalls

1. Invalidate without transition — full skeleton flash.
2. Retry without Query error reset — infinite error loop.
3. Suspense around the whole app shell — refresh blanks nav too; tighten the boundary.
4. Using isPending from Suspense query — not returned; use transition pending / isFetching.
5. Resetting queries on every focus — fighting the cache.
6. Forgetting maxPages — RAM recipe still applies.
7. ErrorBoundary inside Suspense — order is Error outside, Suspense inside (article).
8. Testing refresh only on cold cache — miss the flash.
9. key={Date.now()} on feed to "force refresh" — nuclear remount; loses scroll.
10. Blocking next-page on transition — overkill; next page isn't a full resource remount.

When NOT to use Suspense infinite

If refresh/filter is constant and the team won't use transitions, plain useInfiniteQuery with isPending/isFetching is simpler. Suspense shines when boundaries already orchestrate loading/error for the route.

See also

• Infinite queries
• Suspense transition interplay
• startTransition
• Infinite scroll rams the tab

References

• TanStack Query — Suspense
• TanStack Query — QueryErrorResetBoundary

Demo source

• demos/data-fetching/suspense-infinite-refresh-blanks-feed/ — refresh with/without transition + Retry reset. (Demo host TBD)