React Query Cheatsheet

TanStack Query (formerly known as React Query) is a powerful data-fetching and caching library for React. It helps manage remote state (like API calls) declaratively, with built-in caching, background sync, pagination, and more — removing the need for useEffect, local loading/error state, and boilerplate fetch logic.

Use it when:

• You're fetching remote data (REST, GraphQL, RPC)
• You want stale-while-revalidate caching, pagination, or background refetches
• You want to avoid manually tracking loading, errors, retries, etc.

It complements client state managers (like Zustand or Redux), but often replaces them entirely for server state.

NOTE: Tested with the latest version at time of writing, v5.

Basic Query

Fetch server data and handle loading/error state automatically. Cached by queryKey.

const { data, error, isPending } = useQuery({
  queryKey: ['todos'],
  queryFn: () => fetch('/api/todos').then(res => res.json())
});

Mutations

Use useMutation for POST/PUT/DELETE. Manually trigger and invalidate affected queries after success.

const mutation = useMutation({
  mutationFn: (newTodo) => fetch('/api/todos', {
    method: 'POST',
    body: JSON.stringify(newTodo)
  }),
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] })
});

Invalidate & Refetch

Trigger a fresh fetch manually or after a mutation.

queryClient.invalidateQueries({ queryKey: ['todos'] }); // mark stale
queryClient.refetchQueries({ queryKey: ['todos'] });    // force refetch now

Query Options

Fine-tune behavior: when to run, how long to cache, etc.

useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
  enabled: !!userId,            // don't run until userId exists
  staleTime: 1000 * 60 * 5      // 5 minutes before stale
});

Polling / Intervals

Use refetchInterval to poll at regular intervals.

useQuery({
  queryKey: ['metrics'],
  queryFn: fetchMetrics,
  refetchInterval: 5000 // every 5 seconds
});

Dependent Queries

Only run if a value exists (e.g. after login or param load).

useQuery({
  queryKey: ['account', userId],
  queryFn: () => fetchAccount(userId),
  enabled: !!userId
});

Infinite / Paginated Queries

Fetch paginated data (infinite scroll or cursor-based).

useInfiniteQuery({
  queryKey: ['feed'],
  queryFn: ({ pageParam }) => fetchFeed({ cursor: pageParam }),
  initialPageParam: null,
  getNextPageParam: (lastPage) => lastPage.nextCursor
});