{"id":16882,"library":"react-query","title":"React Query v3 (Legacy)","description":"react-query is a robust and widely adopted library for managing, caching, and synchronizing asynchronous data within React applications. This registry entry refers to version 3.x.x of the `react-query` package, with 3.39.3 being the latest patch provided. Since late 2021, active development and new major versions (v4, v5) have transitioned to the `@tanstack/react-query` package as part of a broader monorepo rebrand. Consequently, the `react-query` package (v3) is now in a maintenance-only phase, receiving critical bug fixes but no new features. Its key differentiators include declarative data fetching via hooks (`useQuery`, `useMutation`), automatic background refetching, efficient data caching with configurable stale-time and cache-time, optimistic updates, and a powerful devtools extension. It significantly reduces boilerplate for data management compared to traditional state management solutions for remote data.","status":"renamed","version":"3.39.3","language":"javascript","source_language":"en","source_url":"https://github.com/tannerlinsley/react-query","tags":["javascript","typescript"],"install":[{"cmd":"npm install react-query","lang":"bash","label":"npm"},{"cmd":"yarn add react-query","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-query","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for React component integration.","package":"react","optional":false}],"imports":[{"note":"For v3, import from 'react-query'. For v4+, use '@tanstack/react-query'.","wrong":"import { useQuery } from '@tanstack/react-query'","symbol":"useQuery","correct":"import { useQuery } from 'react-query'"},{"note":"Primarily used as an ES Module in modern React projects. CommonJS require is generally avoided.","wrong":"const useMutation = require('react-query').useMutation","symbol":"useMutation","correct":"import { useMutation } from 'react-query'"},{"note":"QueryClient is a named export, not a default export.","wrong":"import QueryClient from 'react-query'","symbol":"QueryClient","correct":"import { QueryClient } from 'react-query'"},{"note":"Needed to provide the QueryClient instance to the React component tree.","symbol":"QueryClientProvider","correct":"import { QueryClientProvider } from 'react-query'"}],"quickstart":{"code":"import React from 'react';\nimport { QueryClient, QueryClientProvider, useQuery } from 'react-query';\n\n// Create a client\nconst queryClient = new QueryClient();\n\nfunction Todos() {\n  const { isLoading, error, data } = useQuery('todos', async () => {\n    const response = await fetch('https://jsonplaceholder.typicode.com/todos');\n    if (!response.ok) {\n      throw new Error('Network response was not ok');\n    }\n    return response.json();\n  });\n\n  if (isLoading) return <p>Loading todos...</p>;\n  if (error) return <p>An error occurred: {error.message}</p>;\n\n  return (\n    <div>\n      <h1>Todos</h1>\n      <ul>\n        {data.slice(0, 10).map((todo) => (\n          <li key={todo.id}>{todo.title}</li>\n        ))}\n      </ul>\n    </div>\n  );\n}\n\nexport default function App() {\n  return (\n    <QueryClientProvider client={queryClient}>\n      <Todos />\n    </QueryClientProvider>\n  );\n}","lang":"typescript","description":"This quickstart demonstrates setting up QueryClientProvider and fetching data with useQuery to display a list of todos. It includes basic loading and error states."},"warnings":[{"fix":"Migrate your application to `@tanstack/react-query` by updating package names and reviewing breaking changes in the TanStack Query migration guides (e.g., `isLoading` vs `isInitialLoading`, query function return types). A codemod is available for some migrations.","message":"The `react-query` package is superseded by `@tanstack/react-query` for v4 and beyond. Continuing to use `react-query` (v3) means you will not receive new features or active development, only critical bug fixes.","severity":"breaking","affected_versions":">=3.x"},{"fix":"Ensure you are instantiating and providing a `QueryClient` via `QueryClientProvider` at the root of your application. Directly manipulating `QueryCache` may require changes to use `QueryClient` methods.","message":"In `react-query` v3, `QueryCache` was split into `QueryClient`, `QueryCache`, and `MutationCache`. Direct interaction with `QueryCache` and `MutationCache` is less common, with `QueryClient` serving as the primary interface for configuration and interaction.","severity":"breaking","affected_versions":">=3.0"},{"fix":"Wrap `fetch` calls with logic to `throw new Error()` if `response.ok` is false. For Axios, errors are typically thrown automatically.","message":"Query functions must return a Promise that either resolves with data or *throws* an error for React Query to correctly handle error states. Libraries like `fetch` do not throw on HTTP error codes by default.","severity":"gotcha","affected_versions":">=3.x"},{"fix":"Review `useQuery` calls, especially with the `enabled` option, and update `isLoading` checks to `isInitialLoading` if the query is disabled. Change query functions returning `undefined` to return `null` or throw an error.","message":"When migrating from `react-query` v3 to `@tanstack/react-query` v4, note that `isLoading` for disabled queries behaves differently and might need to be replaced with `isInitialLoading` in specific scenarios. Also, query functions cannot return `undefined` for successful queries in v4.","severity":"gotcha","affected_versions":">=3.x"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Wrap your application or the relevant component tree with `QueryClientProvider`, passing an instance of `QueryClient` as the `client` prop. Place it high in the component hierarchy, typically in `App.js` or `index.js`.","cause":"The `useQuery` or `useMutation` hook was called in a component that is not a descendant of `QueryClientProvider`.","error":"No QueryClient set, use QueryClientProvider to set one"},{"fix":"Ensure `useQuery` is called directly within a React functional component or a custom hook that itself adheres to the rules of hooks.","cause":"Attempting to call `useQuery` (or any React Hook) outside of a functional React component's top level or a custom hook function.","error":"React Hook \"useQuery\" cannot be called inside a callback. React Hooks must be called in a React function component or a custom React Hook function."},{"fix":"Narrow the type of the `error` object before accessing its properties, typically using `if (error instanceof Error)` or a type guard for specific error types like `AxiosError`.","cause":"TypeScript's default error type in catch blocks is `unknown` (since TS 4.4), and React Query's `error` state is typed as `unknown` by default, requiring type narrowing to access properties like `message`.","error":"Property 'message' does not exist on type 'unknown'."}],"ecosystem":"npm","meta_description":null}