Preventing flash when using setQueryData before navigation

[kimsagro1]

Preventing flash when using setQueryData before navigation

TanStack Query version: 5.101.0

Background

I have an article editing page that fetches an article using useQuery. When saving, I fire a mutation that on success:

1. Calls setQueryData to update the cache with the new article data
2. Navigates to another page that uses the same query to display the article

The intent is to pre-populate the cache so the destination page renders immediately without a network request.

Problem

There's a brief flash on the edit page between when setQueryData updates the cache and when the navigation actually occurs. Because the edit page is also subscribed to the same query, the UI re-renders with the new data before unmounting — causing a visible title/content flicker.

What I've tried

Using a useRef to snaphot the initial data

const initialDataRef = useRef<Article | null>(null);
const { isPending, isError, data} = useQuery(...);

if (isPending) return ...
if (isError) return ...

// snapshot data on initial render to prevent a flash of updated content
// before navigation when setQueryData is called in the update mutation
if (initialDataRef.current === null) {
  initialDataRef.current = data
}

Question

Is there a way to combine the behaviour of both approaches — i.e. update the cache data (like setQueryData) without notifying active subscribers on the current page, so the destination page gets the data immediately but the edit page doesn't flash?

Something conceptually like:

queryClient.setQueryData(queryKey, newData, { notify:  'false' })

Or alternatively, is there a pattern for setting query data after navigation has completed rather than before, while still keeping the transition seamless?

Any guidance appreciated!

[ahmedfarid2]

Yes — this is exactly what notifyOnChangeProps is for.

The flash happens because setQueryData notifies every active observer of that query key — including the useQuery on the edit page you're about to leave. notifyOnChangeProps is set per-observer, so you can silence the edit page's observer without affecting the destination page's observer at all. The cache still updates (so the destination renders instantly); the edit page just doesn't re-render.

The clean way is to suppress notifications only during the save → navigate window, using the function form so normal rendering (including the initial pending → success) still works:

const isNavigatingAway = useRef(false);

const { isPending, isError, data } = useQuery({
  queryKey: ['article', id],
  queryFn: fetchArticle,
  // function form: return [] to notify on nothing, undefined for default tracking
  notifyOnChangeProps: () => (isNavigatingAway.current ? [] : undefined),
});

const mutation = useMutation({
  mutationFn: saveArticle,
  onSuccess: (saved) => {
    isNavigatingAway.current = true;            // stop this observer re-rendering
    queryClient.setQueryData(['article', saved.id], saved); // cache updated, no flash here
    navigate(`/articles/${saved.id}`);          // destination reads the fresh cache → no fetch, no flash
  },
});

Why this beats the useRef snapshot you tried: the snapshot freezes the rendered value but the component still re-renders on every cache change — you were fighting the symptom. notifyOnChangeProps: [] stops the re-render at the source, and because it's scoped to this one observer, the destination page is untouched.

Two notes:

• If you'd rather not thread a ref, the simplest alternative is to navigate first and setQueryData in the same tick — once the edit page unmounts, its observer is gone, so there's nothing to flash. Pair it with placeholderData/initialData on the destination if you see a momentary loading state there.
• staleTime on the destination query controls whether it also kicks off a background refetch after mounting from the seeded cache — bump it if you want the seeded data to be treated as fresh.