Mastering React Query: A Complete Guide from Setup to Advanced Usage

Why React Query?

Managing server state in React applications can be tricky. Redux and Context API work well for client-side state, but handling async data (fetching, caching, and synchronization) often leads to boilerplate code and complexity.

Enter React Query: a powerful library that simplifies data fetching, caching, and state synchronization with minimal setup. It eliminates the need for manual state management for server data, making your code cleaner and more efficient.
In this guide, we’ll cover:
✅ Initial Setup: Getting started with React Query
✅ Core Concepts: Fetching data with useQuery
✅ Advanced Techniques: Mutations, pagination, optimistic updates
✅ Best Practices: Optimizing performance and avoiding pitfalls
Let’s get started!

1. Getting started with React Query

a. Installation

First initialize your react project:

terminal

npm create vite@latest react_query_app

This will give you suggestions:

Select a framework ... select: React
Select a variant ... select: Typescript

Now, add React Query to your project:

terminal

npm install @tanstack/react-query

b. Configure the Query Client

Wrap your app with QueryClientProvider to enable React Query:

main.tsx

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App.tsx";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient();

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </StrictMode>
);

That’s it! You’re now ready to fetch and manage server data effortlessly.

2. Fetching Data with useQuery

a. Basic Data Fetching Example

The useQuery hook handles data fetching, caching, and loading states automatically.

App.tsx

import { useQuery } from "@tanstack/react-query";

type Post = {
  userId: number;
  id: number;
  title: string;
  body: string;
};

const fetchPosts = async () => {
  const res = await fetch("https://jsonplaceholder.typicode.com/posts");
  return res.json();
};

function App() {
  const { data, isLoading, error } = useQuery<Post[]>({
    queryKey: ["posts"], // Unique key for caching
    queryFn: fetchPosts, // Function to fetch data
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

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

export default App;

b. Key Benefits:

Automatic Caching: Data is stored and reused efficiently.
Background Updates: Stale data refreshes automatically.
Built-in Loading & Error States: No need for manual state management.

3. Advanced Data Management

a. Pagination with useQuery

Implement smooth pagination using keepPreviousData:

App.tsx

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

type Post = {
  userId: number;
  id: number;
  title: string;
  body: string;
};

const fetchPosts = async ({ limit, page }: { limit: string; page: number }) => {
  const res = await fetch(
    `https://jsonplaceholder.typicode.com/posts?_limit=${limit}&_page=${page}`
  );
  return res.json();
};

function App() {
  const [limit, setLimit] = useState("10");
  const [page, setPage] = useState(1);
  const { data, isLoading, error } = useQuery<Post[]>({
    queryKey: ["posts", limit, page], // Unique key for caching
    queryFn: () => fetchPosts({ limit, page }), // Function to fetch data
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <>
      <ul>
        {data?.map((post) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
      <select onChange={(e) => setLimit(e.target.value)} value={limit}>
        <option value="5">5</option>
        <option value="10">10</option>
        <option value="25">25</option>
        <option value="50">50</option>
      </select>
      <button onClick={() => setPage((p) => Math.max(p - 1, 1))}>
        Previous
      </button>
      <button onClick={() => setPage((p) => p + 1)}>Next</button>
    </>
  );
}

export default App;

b. Modifying Data with useMutation

Create, update, or delete data with mutations:

App.tsx

import { useMutation } from "@tanstack/react-query";

type User = {
  name: string;
  email: string;
};

const addUser = async (newUser: User) => {
  const res = await fetch("https://jsonplaceholder.typicode.com/users", {
    method: "POST",
    body: JSON.stringify(newUser),
  });
  return res.json();
};

function App() {
  const mutation = useMutation({
    mutationFn: addUser,
  });

  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    mutation.mutate({ name: "John Doe", email: "john@example.com" });
  };

  return (
    <form onSubmit={handleSubmit}>
      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? "Saving..." : "Add User"}
      </button>
    </form>
  );
}

export default App;

c. useQuery vs useMutation

Think of these hooks as two different tools for different jobs when working with server data:

useQuery is your data fetcher:
- It executes on page load
- It caches the result
- Refreshes automatically with configuration
useMutation is your data manager:
- It does not execute on page load
- It does not cache the result
- Can only be called manually

d. Understanding invalidateQueries in React Query Mutations

When working with useMutation in React Query, one of the most important concepts is cache invalidation and invalidateQueries is your primary tool for keeping your UI in sync with server data after mutations.

e. What Does invalidateQueries Do?

InvalidateQueries marks cached data as stale and triggers automatic refetches for matching queries. This ensures your UI always displays fresh data after mutations

App.tsx

import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";

type User = {
  name: string;
  email: string;
};

type UserWithId = User & { id: number };

const fetchUsers = async () => {
  const res = await fetch(`https://jsonplaceholder.typicode.com/users`);
  return res.json();
};

const addUser = async (newUser: User) => {
  const res = await fetch("https://jsonplaceholder.typicode.com/users", {
    method: "POST",
    body: JSON.stringify(newUser),
  });
  return res.json();
};

function App() {
  const { data, isLoading } = useQuery<UserWithId[]>({
    queryKey: ["users"],
    queryFn: fetchUsers,
  });
  const queryClient = useQueryClient();
  const mutation = useMutation({
    mutationFn: addUser,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["users"] }); // Refresh user list
    },
  });

  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    mutation.mutate({ name: "John Doe", email: "john@example.com" });
  };

  if (isLoading) return <p>Loading users...</p>;

  return (
    <form onSubmit={handleSubmit}>
      {data?.map((user) => (
        <article key={user.id}>
          <h3>{user.name}</h3>
          <span>{user.email}</span>
        </article>
      ))}
      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? "Saving..." : "Add User"}
      </button>
    </form>
  );
}

export default App;

In this example, After the mutation succeeds, the users query will be invalidated triggering the fetchUsers query to display fresh data.

f. Optimistic Updates for a Smoother UX

Update the UI instantly while waiting for server confirmation:

App.tsx

import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";

type User = {
  name: string;
  email: string;
};

type UserWithId = User & { id: number };

const fetchUsers = async () => {
  const res = await fetch(`https://jsonplaceholder.typicode.com/users`);
  return res.json();
};

const addUser = async (newUser: User) => {
  const res = await fetch("https://jsonplaceholder.typicode.com/users", {
    method: "POST",
    body: JSON.stringify(newUser),
  });
  return res.json();
};

function App() {
  const { data, isLoading } = useQuery<UserWithId[]>({
    queryKey: ["users"],
    queryFn: fetchUsers,
  });
  const queryClient = useQueryClient();
  const mutation = useMutation({
    mutationFn: addUser,
    onError: () => {
      console.log(
        "When this mutation succeeds, this message will be displayed"
      );
    },
    onSuccess: () => {
      console.log("When this mutation fails, this message will be displayed");
      queryClient.invalidateQueries({ queryKey: ["users"] });
    },
    onSettled: () => {
      console.log(
        "Wether it fails or succeeds, When this mutation ends, this message will be displayed"
      );
    },
  });

  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    mutation.mutate({ name: "John Doe", email: "john@example.com" });
  };

  if (isLoading) return <p>Loading users...</p>;

  return (
    <form onSubmit={handleSubmit}>
      {data?.map((user) => (
        <article key={user.id}>
          <h3>{user.name}</h3>
          <span>{user.email}</span>
        </article>
      ))}
      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? "Saving..." : "Add User"}
      </button>
    </form>
  );
}

export default App;

4. Best Practices for Optimal Performance

🚀 Use Descriptive Query Keys: Example: ['posts', { limit: '10', page: 1 }] for better cache management.
🚀 Adjust staleTime & cacheTime: Control how long data remains fresh or cached.
🚀 Prefetch Data for Better UX: Load data before the user needs it.
🚀 Use select for Derived Data: Transform API responses without altering cache.
🚀 Disable Unnecessary Refetches: Set refetchOnWindowFocus: false if not needed.

5. Conclusion

React Query revolutionizes how we handle server state in React apps. By leveraging its powerful caching, background updates, and mutation handling, you can build faster, more responsive applications with less code.

Explore features like Infinite Queries for seamless endless scrolling, Server-Side Rendering (SSR) Support for improved SEO and performance, and Custom Hooks to keep your logic reusable and your codebase clean. With React Query, managing async data becomes intuitive, reducing boilerplate and optimizing performance effortlessly.

Happy coding! 🚀