TanStack Query

Overview

TanStack Query is an open-source data-fetching library that provides a set of tools for managing server state in client-side applications. Originally known as React Query, it has expanded to support multiple frontend frameworks, including Vue, Solid, and Svelte. The library addresses common challenges associated with fetching, caching, and updating asynchronous data, which often involves complex state management logic and potential UI inconsistencies. TanStack Query aims to simplify this process by offering declarative APIs that abstract away much of the underlying complexity.

It is designed for developers building single-page applications (SPAs) or complex UIs that frequently interact with backend APIs. Key use cases include applications requiring real-time data synchronization, optimistic UI updates, background data refetching, and efficient caching strategies. By centralizing server state management, TanStack Query helps developers maintain data consistency across components, reduce the need for manual data invalidation, and improve application performance through intelligent caching. For instance, it provides mechanisms for stale-while-revalidate caching, which serves cached data immediately while simultaneously refetching fresh data in the background, enhancing perceived performance. The TanStack Query overview documentation details these capabilities.

The library's architecture is built around the concept of "queries" and "mutations." Queries are used for reading data, while mutations are for creating, updating, or deleting data on the server. TanStack Query automatically manages the lifecycle of this data, including caching, background refetching, and error handling. This approach reduces the amount of boilerplate code typically required for data fetching and state management, allowing developers to focus on application logic rather than infrastructure concerns. Its framework-agnostic core, exposed through specific framework adapters like React Query, ensures consistent behavior and API across different ecosystems. According to MDN Web Docs on the Fetch API, managing network requests and their subsequent state can be complex, a problem TanStack Query seeks to mitigate.

Key features

• Automatic Caching and Data Synchronization: Manages a cache of server data, automatically refetching and updating when data becomes stale or when specific events trigger invalidation.
• Declarative Data Fetching: Provides hooks (e.g., useQuery, useMutation) for defining data requirements and operations, abstracting away manual fetch calls and state management.
• Optimistic UI Updates: Supports immediate UI updates after a mutation, assuming success, and provides mechanisms to roll back if the server operation fails.
• Background Refetching: Automatically refetches data in the background when components mount, window re-focuses, or network reconnects, ensuring data freshness.
• Query Invalidation and Refetching: Offers fine-grained control over invalidating specific queries or groups of queries, forcing a refetch to ensure UI reflects the latest server state.
• Pagination and Infinite Loading: Includes built-in utilities and patterns for efficiently loading paginated data or implementing infinite scroll experiences.
• Request Deduplication: Prevents multiple identical data requests from being sent simultaneously, optimizing network usage and server load.
• Error Handling and Retries: Provides configurable mechanisms for handling network errors, including automatic retries with exponential backoff.
• Devtools: Ships with a dedicated browser extension for inspecting query states, cache contents, and debugging data flow.

Pricing

As of May 7, 2026, TanStack Query is an entirely open-source project, distributed under the MIT license. There are no direct costs associated with its use, and all features are available without a paid subscription.

For more details, refer to the TanStack Query homepage.

Common integrations

• React: Integrated via @tanstack/react-query, providing custom hooks like useQuery and useMutation for React components. Refer to the React Query documentation.
• Vue: Integrated via @tanstack/vue-query, offering composables for Vue 3 applications. See the Vue Query overview for usage.
• Solid: Integrated via @tanstack/solid-query, providing reactive primitives for Solid.js applications. The Solid Query documentation has details.
• Svelte: Integrated via @tanstack/svelte-query, offering stores and functions for Svelte applications. Consult the Svelte Query guide.
• Axios/Fetch API: Commonly used with standard HTTP clients like Fetch API or Axios for making actual network requests within query functions.
• TypeScript: Fully typed and designed for use with TypeScript, providing strong type inference for queries and mutations. The TypeScript handbook describes its core features.

Alternatives

• SWR: A React Hooks library for data fetching, also using a stale-while-revalidate strategy, developed by Vercel.
• Apollo Client: A comprehensive state management library for GraphQL, offering sophisticated caching and normalization features.
• RTK Query: An add-on for Redux Toolkit designed for efficient data fetching and caching, integrating tightly with Redux.
• Remix Data Loading: Remix's built-in data loading mechanisms handle data fetching and revalidation directly within its framework, often reducing the need for separate libraries.
• Next.js Data Fetching: Next.js provides its own set of data fetching strategies, including server components and route handlers, which can manage server state directly within the framework's architecture.

Getting started

To get started with TanStack Query in a React project, you typically install @tanstack/react-query and set up a QueryClientProvider at the root of your application. This provider makes the query client available to all components that need to fetch or mutate data. Below is a basic example demonstrating how to fetch data using useQuery.

// src/App.tsx
import { QueryClient, QueryClientProvider, useQuery } from '@tanstack/react-query';

const queryClient = new QueryClient();

interface Post {
  id: number;
  title: string;
  body: string;
}

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

  if (isLoading) return <span>Loading posts...</span>;
  if (error) return <span>An error occurred: {error.message}</span>;

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

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

export default App;

This example sets up a QueryClient and wraps the PostsList component with QueryClientProvider. Inside PostsList, useQuery is used to fetch a list of posts from a public API. It automatically manages loading, error, and data states, which are then used to render the UI. The queryKey: ['posts'] uniquely identifies this query, allowing TanStack Query to cache and refetch data efficiently. For further details on installation and advanced usage, consult the React Query installation guide.