React Hooks Reference

Purpose and Scope

This page is a practical reference for the primary React APIs exposed by TanStack Query: query hooks, mutation hooks, status hooks, and option helpers. In React, these APIs are consumed as hooks such as useQuery, useQueries, useInfiniteQuery, useMutation, useIsFetching, and related helpers. They sit on top of the shared TanStack Query model: a QueryClient owns caches and defaults, query keys identify cached server state, query functions return promises, observers connect cached state to framework render systems, and helper functions make reusable options easier to type and share.

The repository evidence for this page is cross-framework rather than React-specific, but it still documents the same contract that React hooks use. The Angular provider reference shows that each adapter must install a QueryClient into the framework dependency system before query APIs can run, while the Angular data-fetching guide states that TanStack Query is promise based and can use any asynchronous client. The background fetching guide is explicitly a framework adaptation of the React guide, replacing useIsFetching with injectIsFetching, which confirms the shared status concept across adapters. Sources: docs/framework/angular/reference/functions/provideTanStackQuery.md, docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md, docs/framework/angular/guides/background-fetching-indicators.md

Relevant Source Files

• docs/config.json — Defines the first-party documentation structure, including the React framework section that contains Overview, Installation, Quick Start, Devtools, Comparison, TypeScript, GraphQL, and React Native entries.
• docs/framework/angular/reference/functions/provideTanStackQuery.md — Documents the framework provider pattern around QueryClient, which corresponds to React’s QueryClientProvider role even though the adapter API is Angular-specific.
• docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md — Explains the promise-based fetching contract that also applies to React queryFn callbacks.
• docs/framework/angular/guides/background-fetching-indicators.md — Mirrors the React background-fetching guide and shows the adapter-specific equivalent of the global fetching status API.
• docs/framework/angular/devtools.md — Shows how devtools are wired as an optional framework feature around the same query and mutation cache concepts that React Devtools inspect.
• docs/community-resources.md — Points readers to maintained community material, including React Query learning resources, generated hooks, query key factories, and type-safe utility libraries.

Core Hook Model

useQuery is the primary React hook for reading asynchronous server state. It accepts an options object with a required queryKey and a queryFn unless a default query function has been configured. The hook subscribes a component to the query cache and returns both result data and lifecycle flags. Important returned fields include data, error, status, fetchStatus, isPending, isSuccess, isError, isFetching, isRefetching, isStale, isPlaceholderData, failureCount, failureReason, and refetch. The query key is the cache identity, while the query function is the promise-producing operation that fetches data.

The same promise contract appears in the Angular guide, which says TanStack Query’s fetching mechanisms are built on Promises and can use native fetch, graphql-request, Angular HttpClient, or other clients after conversion to a promise. For React users, that means a queryFn can wrap REST calls, GraphQL requests, generated clients, or SDK calls as long as it resolves data or throws an error. This design keeps React hooks backend-agnostic: the hook does not need to know whether data came from HTTP, GraphQL, storage, or another async source. Sources: docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

useQueries is the React hook for running a variable set of queries in parallel. Instead of mounting many separate useQuery calls manually, a component can pass a queries array and receive an array of results in the same order. This is useful for fan-out workloads such as loading detail records for a list of ids. useInfiniteQuery builds on the same query model but stores paginated pages under one query key, using initialPageParam, getNextPageParam, getPreviousPageParam, and fetch helpers such as fetchNextPage to support load-more and infinite-scroll user interfaces.

Mutations and Status Hooks

useMutation is the primary React hook for operations that create, update, delete, or otherwise change server state. Unlike queries, mutations are not identified primarily by a cache key used for automatic background refetching. They are imperative operations triggered through mutate or mutateAsync, and their lifecycle can drive optimistic updates, invalidations, retries, and error handling. Typical returned fields include data, error, status, isIdle, isPending, isSuccess, isError, failureCount, variables, submittedAt, mutate, and reset. Mutation callbacks are where applications commonly invalidate related query keys after successful writes.

Status hooks expose aggregate cache activity without subscribing a component to one specific query result. useIsFetching returns a count of currently fetching queries and can be filtered by query key or other query filters. The Angular background-fetching guide shows the same global loading-indicator idea with injectIsFetching, and its frontmatter explicitly records replacement from React terminology. In React, this pattern is used for top-level progress bars, route-level loading indicators, or subtle “refreshing in background” UI that should react to cache activity even when the individual data components remain mounted. Sources: docs/framework/angular/guides/background-fetching-indicators.md

useIsMutating plays the corresponding role for mutations by reporting active mutation count, optionally filtered by mutation key or other mutation filters. useMutationState is more selective: it lets a component inspect mutation records matching filters and project them through a selector. These hooks are useful for global save indicators, disabling duplicate submissions, showing optimistic pending items, or coordinating UI with mutations triggered by a different component. They should be treated as cache-level status readers, not as replacements for the local result object returned by an individual useMutation call.

Option Helpers and Shared Configuration

React’s option helpers such as queryOptions, infiniteQueryOptions, and mutationOptions help centralize configuration while preserving TypeScript inference. A common pattern is to define a function that returns the complete options object for a resource, then reuse it in useQuery, prefetchQuery, cache reads, or invalidation logic. This keeps queryKey, queryFn, staleTime, select, and related options in one place. It also reduces drift between mounted hooks and imperative cache operations because both can consume the same option factory.

The provider setup is the other half of shared configuration. In Angular, provideTanStackQuery(queryClient, ...features) returns framework providers for a QueryClient and optional features such as devtools. In React, the analogous setup is to create a QueryClient and render a QueryClientProvider near the application root. Once the provider is in place, hooks can locate the client implicitly; advanced usage can pass a client explicitly where supported. The important invariant is the same across adapters: hooks and framework functions operate against a configured client that owns cache state and defaults. Sources: docs/framework/angular/reference/functions/provideTanStackQuery.md

Devtools are not hooks, but they are part of the working React hook development loop because they inspect queries and mutations produced by those hooks. The Angular devtools guide documents devtools as an optional feature that can be development-only, production-enabled through a production subpath, or controlled with load options. React users normally install React Query Devtools or compose Query Devtools into TanStack Devtools, then use the panel to inspect query keys, observer counts, fetching state, cache data, stale status, and mutation activity while validating hook behavior. Sources: docs/framework/angular/devtools.md

Compact API Reference

API	Primary use	Key inputs	Result shape
useQuery(options, queryClient?)	Read one cached async resource	queryKey, queryFn, enabled, staleTime, gcTime, select, retry and refetch options	Data, error, status flags, fetch flags, timestamps, refetch
useQueries({ queries }, queryClient?)	Run many queries together	Array of query option objects, optional combine behavior	Array or combined query results
useInfiniteQuery(options, queryClient?)	Read paginated resources as pages	queryKey, queryFn, initialPageParam, page-param getters, max-page options	Pages, page params, fetch-next and fetch-previous helpers
useMutation(options, queryClient?)	Execute writes or side effects	mutationFn, mutation key, lifecycle callbacks, retry options	Mutation status, variables, result data, error, mutate, mutateAsync, reset
useIsFetching(filters?, queryClient?)	Count active query fetches	Query filters such as key matching	Number of fetching queries
useIsMutating(filters?, queryClient?)	Count active mutations	Mutation filters	Number of pending mutations
useMutationState(options, queryClient?)	Select matching mutation records	Filters and selector	Array of selected mutation state values
queryOptions(options)	Reuse typed query options	Query options object	Same options with stronger inference
infiniteQueryOptions(options)	Reuse typed infinite-query options	Infinite query options object	Same options with stronger inference
mutationOptions(options)	Reuse typed mutation options	Mutation options object	Same options with stronger inference

Documentation Navigation and Next Steps

The docs configuration places React hook usage in a wider learning path: React Overview, Installation, Quick Start, Devtools, Comparison, TypeScript, GraphQL, and React Native all appear as first-party React framework entries. For a new codebase, read those pages before treating this reference as a checklist. Start by creating one QueryClient, mounting the provider, and converting one existing data read into useQuery. Then add a mutation for a write path, invalidate or update related query data, and use useIsFetching or Devtools to confirm background behavior. Sources: docs/config.json

For deeper API design context, the community resources page links maintained articles, talks, GraphQL Code Generator, Orval, Query Key Factory, React Query Kit, and related utilities. Those resources are especially useful once a team has many query keys or wants generated, type-safe hooks around REST, OpenAPI, or GraphQL schemas. Treat those utilities as optional layers over the same core primitives described here: a client, stable keys, promise-returning functions, hook subscriptions, mutation execution, and cache-aware status selectors. Sources: docs/community-resources.md