React Query Patterns in 2026: Query Invalidation, Optimistic Updates, and Infinite Scroll

TanStack Query (formerly React Query) has become the standard for server-state management in React applications. The common usage pattern — slap useQuery on every data fetch — works fine for simple cases but breaks down at scale. The patterns that distinguish production codebases from demos: query key factories that make cache invalidation predictable, optimistic mutations that feel instantaneous, and infinite queries that don't re-fetch the entire list on mutation.

This post covers the patterns we use in production applications.

Query Key Factories

Query keys are the foundation of TanStack Query's cache. Ad-hoc keys like ['users', userId] scattered across components make cache invalidation unpredictable. Query key factories centralize key construction:

// src/lib/query-keys.ts
// Centralized query key factory — all cache keys defined in one place

export const queryKeys = {
  // Users
  users: {
    all: () => ['users'] as const,
    lists: () => [...queryKeys.users.all(), 'list'] as const,
    list: (filters: UserFilters) => [...queryKeys.users.lists(), filters] as const,
    details: () => [...queryKeys.users.all(), 'detail'] as const,
    detail: (id: string) => [...queryKeys.users.details(), id] as const,
  },

  // Posts
  posts: {
    all: () => ['posts'] as const,
    lists: () => [...queryKeys.posts.all(), 'list'] as const,
    list: (filters: PostFilters) => [...queryKeys.posts.lists(), filters] as const,
    detail: (id: string) => [...queryKeys.posts.all(), 'detail', id] as const,
    comments: (postId: string) => [...queryKeys.posts.detail(postId), 'comments'] as const,
  },

  // Orders
  orders: {
    all: () => ['orders'] as const,
    byUser: (userId: string) => [...queryKeys.orders.all(), 'user', userId] as const,
    detail: (id: string) => [...queryKeys.orders.all(), 'detail', id] as const,
  },
} as const;

// Usage:
// queryClient.invalidateQueries({ queryKey: queryKeys.posts.lists() })
// → invalidates ALL post lists (any filter combination)
// → does NOT invalidate post details

Query Hooks with Error Boundaries

// src/hooks/queries/useUser.ts
import { useQuery, useSuspenseQuery } from '@tanstack/react-query';
import { queryKeys } from '@/lib/query-keys';
import { api } from '@/lib/api';

// Standard query hook (handles loading/error state inline)
export function useUser(userId: string) {
  return useQuery({
    queryKey: queryKeys.users.detail(userId),
    queryFn: () => api.users.get(userId),
    enabled: !!userId,        // Don't fetch if userId is empty
    staleTime: 5 * 60 * 1000, // Consider fresh for 5 minutes
    gcTime: 10 * 60 * 1000,   // Keep in cache for 10 minutes (formerly cacheTime)
    retry: (failureCount, error) => {
      // Don't retry 404s — user doesn't exist
      if ((error as any)?.status === 404) return false;
      return failureCount < 3;
    },
  });
}

// Suspense variant (throws to nearest Suspense boundary)
export function useSuspenseUser(userId: string) {
  return useSuspenseQuery({
    queryKey: queryKeys.users.detail(userId),
    queryFn: () => api.users.get(userId),
    staleTime: 5 * 60 * 1000,
  });
}

// Usage with Suspense + Error Boundary:
// <ErrorBoundary fallback={<Error />}>
//   <Suspense fallback={<Skeleton />}>
//     <UserProfile userId={id} />
//   </Suspense>
// </ErrorBoundary>
//
// function UserProfile({ userId }) {
//   const { data: user } = useSuspenseUser(userId); // never undefined
//   return <div>{user.name}</div>;
// }

Cache Invalidation Strategies

// src/hooks/mutations/useUpdateUser.ts
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { queryKeys } from '@/lib/query-keys';
import { api } from '@/lib/api';

export function useUpdateUser() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: ({ userId, data }: { userId: string; data: UpdateUserInput }) =>
      api.users.update(userId, data),

    onSuccess: (updatedUser) => {
      // Strategy 1: Update cache directly (no refetch needed)
      queryClient.setQueryData(
        queryKeys.users.detail(updatedUser.id),
        updatedUser,
      );

      // Strategy 2: Invalidate list queries (they'll refetch on next access)
      queryClient.invalidateQueries({
        queryKey: queryKeys.users.lists(),
      });

      // Don't invalidate the detail — we already updated it above
    },

    onError: (error) => {
      console.error('Failed to update user:', error);
    },
  });
}

// More targeted invalidation patterns:
export function useDeletePost() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (postId: string) => api.posts.delete(postId),

    onSuccess: (_, postId) => {
      // Remove from cache entirely (rather than refetching a deleted resource)
      queryClient.removeQueries({
        queryKey: queryKeys.posts.detail(postId),
      });

      // Invalidate all post lists — the deleted post needs to disappear
      queryClient.invalidateQueries({
        queryKey: queryKeys.posts.lists(),
      });
    },
  });
}

Optimistic Updates

Optimistic updates make mutations feel instantaneous by updating the cache before the server responds:

// src/hooks/mutations/useToggleLike.ts
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { queryKeys } from '@/lib/query-keys';

interface Post {
  id: string;
  title: string;
  likeCount: number;
  isLikedByCurrentUser: boolean;
}

export function useToggleLike(postId: string) {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (isLiked: boolean) =>
      isLiked ? api.posts.unlike(postId) : api.posts.like(postId),

    onMutate: async (currentlyLiked: boolean) => {
      // 1. Cancel in-flight queries to prevent race conditions
      await queryClient.cancelQueries({
        queryKey: queryKeys.posts.detail(postId),
      });

      // 2. Snapshot current value for rollback
      const previous = queryClient.getQueryData<Post>(queryKeys.posts.detail(postId));

      // 3. Optimistically update the cache
      queryClient.setQueryData<Post>(
        queryKeys.posts.detail(postId),
        (old) => old ? {
          ...old,
          isLikedByCurrentUser: !currentlyLiked,
          likeCount: old.likeCount + (currentlyLiked ? -1 : 1),
        } : old,
      );

      // 4. Return snapshot for rollback in onError
      return { previous };
    },

    onError: (_err, _variables, context) => {
      // Roll back to previous value if mutation failed
      if (context?.previous) {
        queryClient.setQueryData(
          queryKeys.posts.detail(postId),
          context.previous,
        );
      }
    },

    onSettled: () => {
      // Always refetch to ensure server state is authoritative
      queryClient.invalidateQueries({
        queryKey: queryKeys.posts.detail(postId),
      });
    },
  });
}

Infinite Scroll with useInfiniteQuery

// src/hooks/queries/useInfinitePosts.ts
import { useInfiniteQuery } from '@tanstack/react-query';
import { queryKeys } from '@/lib/query-keys';

interface PostsPage {
  posts: Post[];
  nextCursor: string | null;
  total: number;
}

export function useInfinitePosts(filters: PostFilters = {}) {
  return useInfiniteQuery({
    queryKey: queryKeys.posts.list(filters),
    queryFn: ({ pageParam }) =>
      api.posts.list({ ...filters, cursor: pageParam, limit: 20 }),
    initialPageParam: null as string | null,
    getNextPageParam: (lastPage: PostsPage) => lastPage.nextCursor,
    staleTime: 2 * 60 * 1000,
  });
}

// src/components/PostFeed.tsx
import { useInfinitePosts } from '@/hooks/queries/useInfinitePosts';
import { useIntersectionObserver } from '@/hooks/useIntersectionObserver';

export function PostFeed() {
  const {
    data,
    fetchNextPage,
    hasNextPage,
    isFetchingNextPage,
    status,
  } = useInfinitePosts();

  // Auto-fetch when sentinel element enters viewport
  const sentinelRef = useIntersectionObserver(
    (isIntersecting) => {
      if (isIntersecting && hasNextPage && !isFetchingNextPage) {
        fetchNextPage();
      }
    },
    { threshold: 0.1 },
  );

  if (status === 'pending') return <PostSkeleton count={5} />;
  if (status === 'error') return <ErrorState />;

  const posts = data.pages.flatMap((page) => page.posts);

  return (
    <div>
      {posts.map((post) => (
        <PostCard key={post.id} post={post} />
      ))}

      {/* Sentinel: invisible element at the bottom */}
      <div ref={sentinelRef} className="h-4" />

      {isFetchingNextPage && <PostSkeleton count={3} />}

      {!hasNextPage && posts.length > 0 && (
        <p className="text-center text-gray-500 py-8">
          You've reached the end
        </p>
      )}
    </div>
  );
}

// Intersection Observer hook
function useIntersectionObserver(
  callback: (isIntersecting: boolean) => void,
  options?: IntersectionObserverInit,
) {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const element = ref.current;
    if (!element) return;

    const observer = new IntersectionObserver(
      ([entry]) => callback(entry.isIntersecting),
      options,
    );

    observer.observe(element);
    return () => observer.disconnect();
  }, [callback, options]);

  return ref;
}

Prefetching for Instant Navigation

// src/components/PostList.tsx — Prefetch on hover for instant navigation

import { useQueryClient } from '@tanstack/react-query';
import { queryKeys } from '@/lib/query-keys';

export function PostListItem({ post }: { post: Post }) {
  const queryClient = useQueryClient();

  // Prefetch post detail on hover — ready before user clicks
  const handleMouseEnter = useCallback(() => {
    queryClient.prefetchQuery({
      queryKey: queryKeys.posts.detail(post.id),
      queryFn: () => api.posts.get(post.id),
      staleTime: 5 * 60 * 1000,
    });
  }, [queryClient, post.id]);

  return (
    <Link
      href={`/posts/${post.id}`}
      onMouseEnter={handleMouseEnter}  // Prefetch on hover
      onFocus={handleMouseEnter}       // Accessibility: prefetch on focus too
    >
      {post.title}
    </Link>
  );
}

Global Query Client Configuration

// src/providers/QueryProvider.tsx
'use client';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { useState } from 'react';

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        // Don't refetch on window focus in dev (annoying during development)
        refetchOnWindowFocus: process.env.NODE_ENV === 'production',
        // Don't refetch on reconnect for short disconnects
        refetchOnReconnect: 'always',
        // Global stale time: 1 minute (override per query as needed)
        staleTime: 60 * 1000,
        // Keep in cache for 5 minutes after component unmounts
        gcTime: 5 * 60 * 1000,
        // Retry with exponential backoff, max 3 times
        retry: 3,
        retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30000),
      },
      mutations: {
        // Don't retry mutations by default (idempotency concern)
        retry: false,
        onError: (error) => {
          // Global error handler — show toast, log to Sentry
          console.error('Mutation error:', error);
        },
      },
    },
  });
}

export function QueryProvider({ children }: { children: React.ReactNode }) {
  // Use state to ensure each render gets same QueryClient instance
  const [queryClient] = useState(() => makeQueryClient());

  return (
    <QueryClientProvider client={queryClient}>
      {children}
      {process.env.NODE_ENV === 'development' && (
        <ReactQueryDevtools initialIsOpen={false} />
      )}
    </QueryClientProvider>
  );
}

Working With Viprasol

We architect React applications with production-grade server-state management — from query key design through cache invalidation, optimistic mutations, and prefetching strategies.

What we deliver:

• Query key factory design for predictable cache invalidation
• Mutation patterns with optimistic updates and rollback
• Infinite scroll implementation with cursor-based pagination
• Query client configuration for production workloads
• Migration from Redux/SWR to TanStack Query

→ Discuss your React architecture → Web development services

See Also

• React Performance Optimization
• React Server Components
• Next.js App Router Patterns
• TypeScript Advanced Patterns
• Feature Flag-Driven Development