Beginner’s Guide to React Query (Now TanStack Query)

If you’ve ever tried fetching data in a React app, you know how messy it can get—useEffect here, useState there, maybe some retry logic, a loading spinner, and boom: you’re knee-deep in complexity just to display something simple.

It doesn’t have to be this way.

That’s exactly what React Query—now officially renamed TanStack Query—was built to fix. It's a game-changer when it comes to managing server state in your app.

Let’s break it down and see why it deserves a spot in your React toolbox.

🔍 What is React Query?

React Query is not just a utility function you tack onto a component and move on. It’s a full-blown tool designed to manage server state—data that comes from an external source like an API or backend.

Before libraries like this, developers had to manually handle fetching, error handling, caching, and refetching logic using useEffect, useState, or more complex state tools like Redux or Context. It worked—but scaling that approach cleanly was a pain.

React Query flips that process on its head by letting you declare what you need, and then handling how and when to fetch or refresh it behind the scenes.

It means:

• No boilerplate
• Automatic background updates
• Built-in caching and retries
• And no need for global state just to share API data across components

🏷️ Wait… What’s TanStack Query?

You’ll see both names floating around—React Query and TanStack Query. Same library, same API.

The rename just reflects the broader set of libraries from the same developer (Tanner Linsley), like React Table and React Charts, all grouped under the TanStack umbrella.

But don’t worry—everything you see in this guide applies regardless of which name is used.

⚙️ Installing and Setting Up

Getting started is straightforward.

First, install the package:

npm install @tanstack/react-query

Then you’ll need to set up a QueryClient. This is the engine behind the scenes that manages your queries, caches, and syncing logic.

You only need one, and it’s usually added to the top-level of your app:

import {
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'

const queryClient = new QueryClient()

function App() {
  return (
    <QueryClientProvider client={queryClient}>
    <YourApp />
    </QueryClientProvider>
  )
}

⚠️ Forgetting to wrap your app in QueryClientProvider is one of the most common setup mistakes. Without it, none of the React Query hooks will work.

🔄 Fetching Data with useQuery

Once set up, the easiest way to fetch data is with the useQuery hook.

Here’s a quick example using the JSONPlaceholder API:

import { useQuery } from '@tanstack/react-query'

function Posts() {
  const { data, isLoading, error } = useQuery({
    queryKey: ['posts'],
    queryFn: () =>
    fetch('https://jsonplaceholder.typicode.com/posts').then(res =>
        res.json()
    ),
  })

  if (isLoading) return <p>Loading...</p>
  if (error) return <p>Something went wrong</p>

  return (
    <ul>
    {data.map(post => (
        <li key={post.id}>{post.title}</li>
    ))}
    </ul>
  )
}

Here’s what’s going on:

• queryKey: This uniquely identifies the query and is used for caching.
• queryFn: This is your data-fetching function—can be fetch, axios, etc.
• Returned values like data, isLoading, and error make managing states dead simple.

And the best part? Caching.

If you navigate away from the component and return later, cached data is shown instantly while React Query silently fetches fresh data in the background. No extra logic required.

✋ That’s just the first half of the guide!

Want to go deeper into common mistakes, best practices, and how to avoid stale data traps? Check out the full article here on the Zero To Mastery blog.

P.S. If you’re looking to truly master React in 2025, check out the Complete React Developer Course. It’s helped thousands land jobs at companies like Google, Shopify, and Apple — and could help you do the same.