Queries

Purpose and Scope

A query is TanStack Query's unit of cached asynchronous server state. It pairs a stable query key, which identifies the resource and inputs, with a query function, which returns a Promise for the data. The framework adapter exposes that cached record through framework-native APIs: React uses hooks, Angular uses injection functions and signals, and other adapters follow their own component models. The important mental model is the same across adapters: components declare what data they need, while the QueryClient coordinates fetching, freshness, observers, retries, cache reads, and background refetches.

Sources: docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md, docs/framework/angular/guides/background-fetching-indicators.md

The repository documentation makes the Angular adapter a useful concrete example of this model. An Angular component calls injectQuery with a callback that returns query options, including queryKey and queryFn. The example query uses ['todos'] or ['repoData'] as cache identity and calls an async fetcher for the data. The template then reads signal-style result methods such as isPending(), isError(), isSuccess(), isFetching(), data(), and error(), demonstrating how query state is consumed declaratively without writing a custom loading/error/data state machine.

Sources: docs/framework/angular/guides/background-fetching-indicators.md, docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

Relevant Source Files

• docs/framework/angular/reference/functions/provideTanStackQuery.md - Documents how Angular applications install a QueryClient into dependency injection with provideTanStackQuery, which is required before Angular query APIs can access shared cache state.
• docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md - Shows that query functions are Promise-based and can wrap Angular HttpClient, fetch, graphql-request, or other async clients.
• docs/framework/angular/guides/background-fetching-indicators.md - Provides the clearest source-backed example of query lifecycle flags in a component template and a global background-fetching indicator.
• docs/framework/angular/devtools.md - Explains devtools integration for inspecting queries and mutations, including Angular-specific withDevtools setup and loading behavior.
• docs/config.json - Shows that the documentation site is organized by framework sections, reinforcing that query concepts are shared while adapter APIs differ.
• docs/community-resources.md - Points to maintainer-authored articles, media, and utilities that expand on practical query design, query keys, generated clients, and cache management.

Query Model and Setup

Every running query belongs to a QueryClient. In Angular, the documented setup function is provideTanStackQuery(queryClient, ...features): Provider[], which installs the providers necessary to enable TanStack Query functionality for an application. The same page shows both standalone bootstrap and NgModule-based setup, and it also supports passing an InjectionToken that provides a QueryClient. That token-based form is described as an advanced optimization for lazy-loaded routes or components that should include TanStack Query only when needed while still sharing a client instance.

Sources: docs/framework/angular/reference/functions/provideTanStackQuery.md

Once the client is available, a component-level query describes the cache entry rather than manually orchestrating request effects. In the Angular HttpClient guide, injectQuery returns a query object from options containing queryKey: ['repoData'] and a queryFn that fetches GitHub repository data. Because TanStack Query is Promise-based, Angular HttpClient observables are converted with lastValueFrom or firstValueFrom. This is an important boundary: TanStack Query does not prescribe REST, GraphQL, or Angular-specific transport. It asks for a Promise that resolves with data or rejects with an error.

Sources: docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

@Component({
  // ...
})
class ExampleComponent {
  private readonly http = inject(HttpClient)
 
  readonly query = injectQuery(() => ({
    queryKey: ['repoData'],
    queryFn: () =>
      lastValueFrom(
        this.http.get('https://api.github.com/repos/tanstack/query'),
      ),
  }))
}

Lifecycle States and Status Flags

The query result exposes two related kinds of state. The first is the main lifecycle status: pending, error, or success. The Angular background-fetching guide renders Loading... while todosQuery.isPending() is true, shows the error message when todosQuery.isError() is true, and renders data only after todosQuery.isSuccess() is true. This maps directly to the practical UI decisions developers make: show a first-load placeholder, show a recoverable error state, or render the data-backed view.

Sources: docs/framework/angular/guides/background-fetching-indicators.md

The second kind of state is fetch activity. A query can already have successful data and still be fetching again in the background. The same Angular example checks todosQuery.isFetching() inside the success branch and displays Refreshing... while existing todos remain visible. That distinction is central to TanStack Query's user experience: successful cached data should not disappear just because a refetch is happening. Instead, the query result lets the UI communicate background activity separately from first-load pending state.

Sources: docs/framework/angular/guides/background-fetching-indicators.md

@if (todosQuery.isPending()) {
  Loading...
} @else if (todosQuery.isError()) {
  An error has occurred: {{ todosQuery.error().message }}
} @else if (todosQuery.isSuccess()) {
  @if (todosQuery.isFetching()) {
    Refreshing...
  }
  @for (todos of todosQuery.data(); track todo.id) {
    <todo [todo]="todo" />
  }
}

Framework Adapter Consumption

Framework adapters translate the shared query model into the idioms of each UI runtime. The docs configuration lists framework-specific documentation sections such as React, Solid, Vue, Svelte, and Lit, while the provided Angular pages show the Angular-specific consumption shape. In Angular, query APIs are integrated with dependency injection and signal-style reads; setup is done through providers, and component templates call methods on the query result. In React, the same model is surfaced through useQuery, but the cache identity, Promise-returning query function, and lifecycle flags remain the common contract.

Sources: docs/config.json, docs/framework/angular/reference/functions/provideTanStackQuery.md, docs/framework/angular/guides/background-fetching-indicators.md

The Angular HttpClient guide also clarifies how framework-native data clients fit into that adapter boundary. HttpClient brings Angular benefits such as testing helpers, interceptors integrated with dependency injection, awareness of pending tasks for unit tests and SSR, and built-in SSR request caching. TanStack Query can use it, but the query function still resolves through a Promise. Specialized clients like graphql-request and the browser fetch API are equally valid when wrapped as Promise-returning query functions, making the query layer transport-agnostic while preserving cache behavior.

Sources: docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

Background Fetching and Inspection

For page-level or app-level loading indicators, individual query flags are not always enough. The Angular background-fetching guide shows injectIsFetching() in a GlobalLoadingIndicatorComponent, where the template displays a message whenever any query is fetching in the background. This is a different view over the same cache activity: instead of asking one query result whether it is fetching, the component observes aggregate fetching state from the client. Use this for global progress bars, route-level indicators, or subtle network activity affordances.

Sources: docs/framework/angular/guides/background-fetching-indicators.md

Devtools make those same query records visible during development. The Angular devtools page explains that devtools help debug and inspect queries and mutations, and that they can be enabled by adding withDevtools to provideTanStackQuery. By default, Angular Query Devtools are included only in development mode bundles. A production subpath exists for deliberate production loading, and the loadDevtools option can be set to auto, true, or false. This makes inspection an opt-in feature around the same QueryClient setup.

Sources: docs/framework/angular/devtools.md, docs/framework/angular/reference/functions/provideTanStackQuery.md

API Components

Practical Next Steps

When adding a new query, first decide the cache identity and encode it in a query key that includes the resource and inputs. Then write a Promise-returning query function around the transport that best fits the framework and backend. In Angular, provide a single QueryClient with provideTanStackQuery, use injectQuery inside components, branch UI on pending/error/success, and show background refresh with isFetching() instead of replacing already-rendered data. For broader design guidance, the community resources page points to maintainer articles and utilities such as Query Key Factory, GraphQL Code Generator, Orval, and React Query Kit.

Sources: docs/framework/angular/reference/functions/provideTanStackQuery.md, docs/framework/angular/guides/background-fetching-indicators.md, docs/community-resources.md