Data Fetching with TanStack Query

Every React dev writes this component at some point. You need a user profile from the API, so you reach for useEffect + fetch, add a loading flag, add an error state… and before you know it, your "simple fetch" looks like this:

import { useState, useEffect } from 'react';

export function UserProfile({ userId }) {
  // Three pieces of state just to track ONE request
  const [user, setUser] = useState(null);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    // Guard flag: if userId changes mid-request, the OLD response
    // must not overwrite the NEW one (the classic race condition)
    let ignore = false;
    const controller = new AbortController();

    setIsLoading(true);
    setError(null);

    async function load() {
      try {
        const res = await fetch(`/api/users/${userId}`, {
          signal: controller.signal,
        });
        if (!res.ok) {
          throw new Error(`Request failed with status ${res.status}`);
        }
        const data = await res.json();
        if (!ignore) {
          setUser(data);
        }
      } catch (err) {
        // AbortError is not a real error — we cancelled it ourselves
        if (err.name !== 'AbortError' && !ignore) {
          setError(err);
        }
      } finally {
        if (!ignore) {
          setIsLoading(false);
        }
      }
    }

    load();

    // Cleanup: runs when userId changes or the component unmounts
    return () => {
      ignore = true;
      controller.abort();
    };
  }, [userId]); // refetch whenever userId changes

  if (isLoading) return <p>Loading…</p>;
  if (error) return <p>Error: {error.message}</p>;
  if (!user) return null;

  return (
    <div>
      <h2>{user.name}</h2>
      <p>{user.role}</p>
    </div>
  );
}

Almost 60 lines — and honestly, this is the careful version. Most tutorials skip the ignore flag and the AbortController, which means most real apps ship the race condition. And even this careful version still has real problems:

• No cache. Navigate away and back? Full loading spinner again, even for data you fetched 5 seconds ago.
• No deduplication. Two components need the same user? Two identical requests hit your API.
• No retries. One flaky network blip = error screen. The user has to refresh manually.
• No background refresh. Data silently goes stale while the tab sits open.
• Copy-pasted everywhere. Every fetching component repeats this same 60-line dance, with slightly different bugs.

Ang totoo niyan: fetching data is not the hard part. Managing server state over time — caching it, syncing it, invalidating it — is the hard part. That's exactly the job TanStack Query was built for.

TanStack Query (formerly React Query) is a server-state manager. It treats data from your API as a cache that needs syncing — not as ordinary component state. You describe what data you need and how to get it; the library handles everything else:

Setup is two steps: install the package, then wrap your app in a provider — the same pattern you already know from useContext.

npm install @tanstack/react-query
npm install -D @tanstack/react-query-devtools

import React from 'react';
import ReactDOM from 'react-dom/client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import App from './App';

// One client for the whole app — it OWNS the cache.
// Create it OUTSIDE the component so it isn't recreated on re-render.
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60 * 1000, // data is "fresh" for 1 minute (more in section 10)
    },
  },
});

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
      {/* Devtools only render in development builds */}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  </React.StrictMode>
);

A query needs exactly two things: a queryKey (the cache's name for this data) and a queryFn (any async function that returns the data or throws). In return you get the full request lifecycle as plain values — no useState, no useEffect, no ignore flags.

Try it below. Mount the component and watch isPending do its thing. Then unmount and mount again — instant data, because the cache already has it, while a background refetch quietly updates it. One heads-up: since @tanstack/react-query isn't installed in this article's codebase, the demo simulates the library's behavior with plain React (an in-memory Map as the cache, setTimeout as the network). The Code tab shows the real TanStack Query code you'd write.

The queryKey array is the single most important concept in the whole library. It plays two roles at once:

• Cache identity: ['user', 1] and ['user', 2] are two separate cache entries. Same key anywhere in the app = same shared data, one request.
• Dependency array: when any value inside the key changes, TanStack Query automatically fetches the new key — like a useEffect dependency array, but with caching built in.

Rule of thumb: everything your queryFn uses must be in the key. Fetching page 3 of search results for "shoes"? The key is ['products', { search: 'shoes', page: 3 }]. Try the demo — pick a user, then come back to a user you already visited (again, cache simulated in-article; real code in the Code tab):

When a queryFn throws, TanStack Query doesn't give up immediately — it retries (3 times by default) with exponential backoff before setting isError. That means one flaky network blip usually never reaches your users at all.

The demo below simulates the retry flow. Leave the failure toggle on and watch the backoff (1s, then 2s). Or — my favorite trick — start a fetch, then uncheck the toggle mid-retry to "fix the server" and watch a retry quietly succeed, exactly like a real transient outage:

Queries read; mutations write (POST, PUT, DELETE). The magic is what happens after the write: invalidateQueries marks the related cached data as stale, and TanStack Query refetches it automatically. Your todo list updates without you ever manually syncing state.

Add a todo below and read the log: the POST fires, then invalidateQueries(['todos']), then the list refetches itself. (Server + cache simulated in plain React so it runs here.)

The flow to internalize — this is the pattern you'll use for 90% of writes:

mutate(newTodo)
  → POST /api/todos                     (mutationFn runs)
  → onSuccess fires
  → invalidateQueries({ queryKey: ['todos'] })
  → every ['todos'] query is marked STALE
  → active ones refetch automatically
  → every component using useQuery(['todos']) re-renders with fresh data

For interactions that should feel instant — likes, toggles, drag reorders — waiting even 300ms for the server feels laggy. An optimistic update flips the order: update the UI first, send the request, and roll back only if the server says no. Users get instant feedback; the rare failure snaps back gracefully.

Click the like button — the count jumps before the "network" responds. Then turn on the failure toggle and watch the rollback:

The three-step recipe in the Code tab is always the same:

• onMutate: cancel in-flight refetches, snapshot the current cache, apply the optimistic value, return the snapshot as context
• onError: restore the snapshot from context — the rollback
• onSettled: invalidate, so the cache re-syncs with the server either way

Since the page number lives in the query key, pagination is almost free: ['products', page] gives each page its own cache entry. The one UX problem: clicking "Next" on an uncached page normally blanks the list to a spinner. Fix it with placeholderData: keepPreviousData — the old page stays on screen (flagged by isPlaceholderData) until the new one arrives:

import { useQuery, keepPreviousData } from '@tanstack/react-query';
import { useState } from 'react';

async function fetchProducts(page) {
  const res = await fetch(`/api/products?page=${page}&limit=10`);
  return res.json(); // { items: [...], hasMore: true }
}

export function ProductList() {
  const [page, setPage] = useState(1);

  const { data, isPending, isPlaceholderData } = useQuery({
    queryKey: ['products', page], // page is part of the key
    queryFn: () => fetchProducts(page),
    // v5: keepPreviousData is a helper you pass to placeholderData.
    // (The old v4 boolean option `keepPreviousData: true` is gone.)
    placeholderData: keepPreviousData,
  });

  if (isPending) return <p>Loading products…</p>;

  return (
    <div style={{ opacity: isPlaceholderData ? 0.6 : 1 }}>
      <ul>
        {data.items.map((product) => (
          <li key={product.id}>{product.name}</li>
        ))}
      </ul>
      <button onClick={() => setPage((p) => Math.max(p - 1, 1))} disabled={page === 1}>
        Previous
      </button>
      <span> Page {page} </span>
      <button
        onClick={() => setPage((p) => p + 1)}
        disabled={isPlaceholderData || !data.hasMore}
      >
        Next
      </button>
    </div>
  );
}

For infinite scroll / "Load more" feeds, switch to useInfiniteQuery — it accumulates pages into data.pages and tracks the cursor for you:

import { useInfiniteQuery } from '@tanstack/react-query';

export function Feed() {
  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
    useInfiniteQuery({
      queryKey: ['feed'],
      queryFn: ({ pageParam }) =>
        fetch(`/api/feed?cursor=${pageParam}`).then((res) => res.json()),
      initialPageParam: 0, // required in v5
      // Return the next cursor, or undefined when there are no more pages
      getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
    });

  return (
    <div>
      {data?.pages.map((page) =>
        page.items.map((post) => <PostCard key={post.id} post={post} />)
      )}
      <button
        onClick={() => fetchNextPage()}
        disabled={!hasNextPage || isFetchingNextPage}
      >
        {isFetchingNextPage
          ? 'Loading more…'
          : hasNextPage
            ? 'Load more'
            : 'No more posts'}
      </button>
    </div>
  );
}

These two settings confuse everyone, pero simple lang talaga once you see that cached data moves through three states:

fetched ──[staleTime elapses]──▶ stale ──[unused + gcTime elapses]──▶ garbage-collected

FRESH   : "this data is good" — components use it, NO refetch happens
STALE   : "usable but maybe outdated" — shown instantly, refetched in background
GC'd    : removed from memory — next use is a full loading-spinner fetch

With the default staleTime: 0, every mount and every window focus triggers a background refetch. That's safe but chatty. Tune it per query based on how often the data actually changes:

// Country list — changes basically never
useQuery({
  queryKey: ['countries'],
  queryFn: fetchCountries,
  staleTime: Infinity,        // never refetch automatically
});

// Product catalog — changes a few times a day
useQuery({
  queryKey: ['products', page],
  queryFn: () => fetchProducts(page),
  staleTime: 5 * 60 * 1000,   // fresh for 5 minutes
});

// Notifications — should feel live
useQuery({
  queryKey: ['notifications'],
  queryFn: fetchNotifications,
  staleTime: 0,               // always stale → refetch on focus/mount
  refetchInterval: 30 * 1000, // and poll every 30s
});

Honest talk: hindi ito kailangan ng lahat ng app. TanStack Query shines when the client owns interactive server state. Skip it when:

• You're in a React Server Component. A one-shot read that renders on the server needs no client cache at all — just await the fetch:

// No "use client", no useQuery, no loading state to manage.
// The server fetches, renders HTML, and Next.js handles caching.
export default async function UsersPage() {
  const res = await fetch('https://api.example.com/users', {
    next: { revalidate: 60 }, // Next.js-level caching
  });
  const users = await res.json();

  return (
    <ul>
      {users.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

• Tiny apps with 1–2 fetches that load once and never change — a well-written useEffect (or a small custom hook like the one from the custom hooks post) is fine. Adding a library to fetch one config file is over-engineering.
• You prefer a smaller API: SWR (by Vercel) covers the same core ideas — cache keys, revalidate on focus, dedupe — with fewer features and a lighter footprint. If your app is mostly reads with simple writes, SWR is a legit choice. TanStack Query pulls ahead on mutations, optimistic updates, infinite queries, and devtools.

// ❌ BAD: new Date() changes every render → new key → refetch forever
useQuery({
  queryKey: ['report', new Date()],
  queryFn: fetchReport,
});

// ✅ GOOD: derive a stable value first
const today = new Date().toISOString().slice(0, 10); // "2026-07-18"
useQuery({
  queryKey: ['report', today],
  queryFn: () => fetchReport(today),
});

// ❌ BAD: fetching in useEffect and pushing into TanStack Query manually —
// you get NONE of the dedupe/retry/race protection
useEffect(() => {
  fetch('/api/users')
    .then((res) => res.json())
    .then((data) => queryClient.setQueryData(['users'], data));
}, [queryClient]);

// ✅ GOOD: let the library own the fetch
useQuery({ queryKey: ['users'], queryFn: fetchUsers });

const { data: user } = useQuery({
  queryKey: ['me'],
  queryFn: fetchMe,
});

// ✅ This query won't run until user?.id actually exists
const { data: orders } = useQuery({
  queryKey: ['orders', user?.id],
  queryFn: () => fetchOrders(user.id),
  enabled: !!user?.id,
});

Cement all of this by building a GitHub repo explorer (the GitHub API is free, no key needed for light use):

• Search input → useQuery({ queryKey: ['repos', searchTerm], ... }) hitting https://api.github.com/search/repositories?q=…
• Click a repo → detail view with ['repo', owner, name] — verify revisits are instant from cache
• Paginate results with placeholderData: keepPreviousData — no spinner flash between pages
• Add a client-side "favorite" toggle with an optimistic update (fake the server with a delay, like our demos did)
• Open the React Query Devtools and watch each query go fresh → stale → inactive → garbage-collected

If you can explain to a friend why the detail view is instant the second time — sa cache galing, hindi sa network — you've got it.

Keep practicing! 💪 The day TanStack Query really clicked for me was the day I stopped thinking "how do I fetch this?" and started thinking "what is this data's name, and when does it go stale?" Once server state has proper names, whole categories of bugs — race conditions, stale screens, duplicate requests — just stop existing in your codebase.