What is React Query and Why You Should Use It? | ZextOverse
What is React Query and Why You Should Use It?
You've written the "useEffect". You've added the "useState" for loading, error, and data. You've handled the cleanup. You've done it a hundred times. There's a better way.
React is extraordinarily good at one thing: rendering UI as a function of state. Give it state, it gives you a screen. Change the state, the screen updates. Clean, predictable, composable.
What React does not give you is any opinion on where that state comes from.
For local, ephemeral UI state — whether a modal is open, which tab is selected, what the user typed in a field — useState and useReducer are perfect. But the moment you need to fetch data from a server, the situation gets complicated fast.
Consider what a "simple" data-fetching pattern in vanilla React actually requires:
And this is still the happy path. We haven't handled:
Caching: if the user navigates away and back, do we fetch again?
Deduplication: if two components mount simultaneously and both need this user, do we send two requests?
Background refetching: if the data might have changed, when do we refresh?
Stale data: should we show the old data while fetching the new?
Retry logic: if the request fails, should we try again?
Pagination: how do we load more items without blowing up memory?
Optimistic updates: how do we reflect a mutation immediately before the server confirms it?
This is server state management — and it's a fundamentally different problem from UI state management. React Query (officially known as TanStack Query) exists to solve exactly this.
What Is React Query?
React Query is an asynchronous state management library for React (with adapters for Vue, Solid, Svelte, and Angular via TanStack Query). It provides a set of hooks and utilities that handle the full lifecycle of server-side data in your application.
Share this article:
At its core, React Query introduces two primitives:
Queries — for reading data from a server (GET)
Mutations — for writing data to a server (POST, PUT, PATCH, DELETE)
But the real value isn't in those primitives themselves. It's in everything React Query automatically manages around them: a smart, normalized cache with configurable staleness, background synchronization, request deduplication, retry strategies, garbage collection, and developer tooling.
Installed by more than 10 million projects per week on npm, React Query has become the de facto standard for server state in React applications.
// app/layout.tsx (Next.js App Router)
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
const queryClient = new QueryClient();
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<QueryClientProvider client={queryClient}>
{children}
<ReactQueryDevtools initialIsOpen={false} />
</QueryClientProvider>
</body>
</html>
);
}
Note for Next.js App Router users: since QueryClientProvider is a client component, you'll want to extract it into a 'use client' wrapper component. The TanStack Query docs cover this pattern in detail.
The useQuery Hook
The useQuery hook is your primary tool for fetching and caching data. Let's rewrite the earlier example:
import { useQuery } from '@tanstack/react-query';
async function fetchUser(userId: string): Promise<User> {
const res = await fetch(`/api/users/${userId}`);
if (!res.ok) throw new Error('Failed to fetch user');
return res.json();
}
function UserProfile({ userId }: { userId: string }) {
const { data: user, isLoading, isError, error } = useQuery({
queryKey: ['user', userId],
queryFn: () => fetchUser(userId),
});
if (isLoading) return <Spinner />;
if (isError) return <ErrorMessage error={error} />;
return <UserCard user={user!} />;
}
Same behavior, a fraction of the code. But more importantly: you're now getting all the features you weren't handling before — caching, deduplication, background refetching — for free.
The queryKey
The queryKey is the most important concept in React Query. It's an array that uniquely identifies a query. React Query uses it to:
Store and retrieve results from the cache
Deduplicate concurrent requests with the same key
Invalidate specific slices of data after mutations
Keys are hierarchical and serializable:
// A list of all users
useQuery({ queryKey: ['users'], queryFn: fetchUsers });
// A specific user
useQuery({ queryKey: ['user', userId], queryFn: () => fetchUser(userId) });
// A user's posts, filtered
useQuery({
queryKey: ['user', userId, 'posts', { status: 'published' }],
queryFn: () => fetchUserPosts(userId, 'published'),
});
When you invalidate ['user', userId], React Query also invalidates everything nested under that key — including ['user', userId, 'posts', ...]. This makes cache management feel intuitive rather than brittle.
queryFn: Bring Your Own Fetcher
React Query is agnostic about how you fetch. The queryFn can use fetch, axios, ky, a GraphQL client, or any async function that returns data or throws an error:
// With axios
queryFn: () => axios.get(`/api/users/${userId}`).then(r => r.data)
// With a GraphQL client
queryFn: () => graphqlClient.request(USER_QUERY, { userId })
// With tRPC
queryFn: () => trpc.user.byId.query({ userId })
Key Features Deep Dive
Caching and Stale-While-Revalidate
React Query implements the stale-while-revalidate (SWR) pattern. When you navigate back to a screen whose data is already cached, React Query:
Immediately returns the cached data (so the UI renders instantly)
Fetches fresh data in the background
Updates the UI if the fresh data differs
You control how long data is considered "fresh" with staleTime:
useQuery({
queryKey: ['user', userId],
queryFn: () => fetchUser(userId),
staleTime: 1000 * 60 * 5, // data is fresh for 5 minutes
});
With staleTime: Infinity, data is never automatically refetched — useful for static reference data like country lists or configuration.
Automatic Retries
Failed requests are automatically retried 3 times (with exponential backoff) before the query enters the error state. Fully configurable:
When a user tabs away and comes back, React Query refetches stale queries automatically. This means your users almost never see stale data without you writing a single line of polling logic. Disable it per-query or globally if needed:
If two components mount at the same time and both call useQuery with the same key, React Query sends exactly one request and shares the result with both. This is automatic and requires no coordination on your part.
Mutations with useMutation
Reading data is only half the story. The useMutation hook handles write operations:
After a successful mutation, invalidateQueries marks the relevant cache entries as stale, triggering a background refetch. The UI stays consistent without manual state updates.
Optimistic Updates
For a snappier UX, you can update the cache before the server responds and roll back if the request fails:
const mutation = useMutation({
mutationFn: updateUsername,
onMutate: async (newUsername) => {
// Cancel any in-flight refetches
await queryClient.cancelQueries({ queryKey: ['user', userId] });
// Snapshot the current value
const previousUser = queryClient.getQueryData(['user', userId]);
// Optimistically update the cache
queryClient.setQueryData(['user', userId], (old: User) => ({
...old,
username: newUsername,
}));
// Return the snapshot for rollback
return { previousUser };
},
onError: (err, newUsername, context) => {
// Roll back on error
queryClient.setQueryData(['user', userId], context?.previousUser);
},
onSettled: () => {
queryClient.invalidateQueries({ queryKey: ['user', userId] });
},
});
The result: the UI updates instantly, and if the server rejects the change, it snaps back transparently.
Pagination and Infinite Queries
React Query ships first-class support for paginated and infinite-scroll data via useInfiniteQuery:
React Query handles merging pages, tracking cursors, and managing the loading state for each page individually — no custom reducer required.
The DevTools
The @tanstack/react-query-devtools package adds a floating panel to your app in development that shows:
Every active query and its current state (fresh, stale, fetching, paused, inactive)
The full cache contents, inspectable in real time
The ability to manually trigger refetches, invalidations, or resets
Query timing and observer counts
For debugging caching behavior — especially as applications grow — the DevTools are indispensable. They make the invisible cache visible.
React Query vs. The Alternatives
Feature
React Query
SWR
Redux Toolkit Query
Apollo Client
Protocol
Any
Any
Any
GraphQL only
Cache control
Fine-grained
Basic
Fine-grained
Fine-grained
Mutations
First-class
Manual
First-class
First-class
Optimistic updates
Built-in
Manual
Built-in
Built-in
Infinite queries
Built-in
Built-in
Manual
Manual
DevTools
Excellent
Basic
Redux DevTools
Apollo Studio
Bundle size
~13 kB
~4 kB
Included in RTK
~30 kB
Learning curve
Moderate
Low
Moderate (Redux)
High
SWR (by Vercel) is React Query's closest competitor. It's lighter and simpler, making it a strong choice for smaller projects or Next.js apps with basic fetching needs. React Query wins in complex scenarios requiring fine-grained cache control, rich mutation lifecycle hooks, or sophisticated pagination.
Redux Toolkit Query (RTK Query) is a strong contender if you're already using Redux. It integrates tightly with the Redux store and DevTools. If you're not already on Redux, the overhead of adopting it for server state alone is rarely justified.
When Should You Use React Query?
React Query shines in applications with:
Multiple components that share the same remote data — the deduplication and cache sharing alone justify adoption
Complex mutation flows — especially when mutations affect multiple queries
UX requirements for perceived performance — stale-while-revalidate makes apps feel instant
Pagination or infinite scroll — useInfiniteQuery is genuinely excellent
Real-time or frequently-updated data — polling and background refetch are first-class features
You might not need React Query if:
You're building a mostly static site with minimal fetching (Next.js Server Components may be sufficient)
You have a single fetch at the top of your tree with no sharing or caching requirements
You're already deeply invested in an Apollo + GraphQL setup
A Note on Next.js App Router
With the Next.js App Router and React Server Components (RSC), some of the problems React Query solves can be addressed server-side: you can fetch data directly in Server Components without any client-side state management.
However, React Query remains highly relevant for:
Client-side interactivity: data that changes based on user actions (filters, searches, pagination)
Mutations: useMutation is not replicated by RSC
Real-time updates: polling, refetch-on-focus, and WebSocket integration
Shared client state: when multiple client components need the same data
The two paradigms are complementary. Fetch static or initial data on the server; use React Query for dynamic, interactive, and mutation-heavy workflows on the client.
Conclusion
React Query doesn't add a new paradigm to React — it completes the one that was already there. React handles UI state beautifully. React Query handles server state with the same elegance.
The cognitive overhead of data fetching — loading states, error handling, caching, deduplication, retries, invalidation — dissolves into a handful of well-designed hooks. Your components become leaner. Your bugs become fewer. Your users see faster, more consistent UIs.
If you're writing useEffect + useState to fetch data in 2025, you're solving a problem that's already been solved. React Query is the solution the community converged on — and for good reason.
Start with useQuery. Add useMutation when you need to write. Let the cache do the rest.
