Angular Query Experimental

Purpose and Scope

Angular Query is the Angular framework adapter for TanStack Query, exposed through the experimental package name shown in the official Angular examples. It brings the shared TanStack Query server-state model into Angular applications through providers, dependency injection, and signal-friendly functions instead of React hooks. Use it when an Angular component needs cached asynchronous data with query keys, background refetching, mutation visibility, and devtools inspection, while still fitting naturally into Angular application configuration and templates. The adapter remains centered on a QueryClient, so the same cache and lifecycle vocabulary applies across frameworks even though the public entry points are Angular functions.

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

The Angular docs should be read as adapter documentation, not as a separate cache implementation. The repository documentation says TanStack Query fetching is promise based and agnostic to the data-fetching client, which means Angular applications can choose Angular HttpClient, browser fetch, GraphQL clients, or other promise-producing libraries. Angular-specific guidance matters most at the boundary where framework services, observables, dependency injection, and templates meet the QueryClient cache. In practice, the adapter lets Angular code declare what data it needs while TanStack Query coordinates freshness, retries, background updates, and observers behind that declaration.

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

Relevant Source Files

• docs/framework/angular/reference/functions/provideTanStackQuery.md — Defines the documented provider API, accepted QueryClient or InjectionToken input, optional QueryFeatures, devtools feature usage, and standalone plus NgModule examples.
• docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md — Explains how Angular HttpClient, fetch, GraphQL clients, observables, and promises fit into Angular Query query functions.
• docs/framework/angular/devtools.md — Documents Angular devtools enablement, production subpath behavior, loadDevtools options, and reactive option callbacks.
• docs/framework/angular/guides/background-fetching-indicators.md — Shows Angular template usage with injectQuery result signals and global background fetching with injectIsFetching.
• docs/config.json — Provides repository docs configuration and search/navigation metadata that places these pages in the generated TanStack Query documentation site.
• docs/community-resources.md — Points readers toward community learning resources that supplement the framework-specific Angular documentation.

Core Primitives

The first primitive is the QueryClient. It owns the cache and is passed into Angular through provideTanStackQuery. The documented function signature returns Angular providers and accepts either a QueryClient instance or an InjectionToken that provides one. Passing a direct instance is the normal application setup path, while the InjectionToken path is described as an advanced optimization for lazy loaded routes or components. That optimization can keep TanStack Query out of the main application bundle while still sharing a client where the lazy boundary needs one, but the docs explicitly frame main application configuration as preferable for most applications.

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

The second primitive is an injected query function. In component code, injectQuery receives a callback that returns query options such as a queryKey and queryFn. The examples use Angular signal-style reads in templates, so status checks and data access appear as function calls. A component can branch on pending, error, and success states, show a separate refresh indicator when a successful query is fetching again, and iterate over returned data. For global loading UI, injectIsFetching produces a signal-like value that can be read in a shared indicator component to show that queries are fetching in the background.

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

Provider Setup and Configuration

For a standalone Angular application, install the provider in the bootstrap configuration by calling provideTanStackQuery with a new QueryClient. The NgModule example uses the same provider call inside the module providers array, so the adapter supports both modern standalone configuration and module-based Angular applications. Optional features are passed after the client argument. The documented feature example is withDevtools, which augments the provider setup rather than requiring every component to import devtools. This shape keeps application-wide Query configuration close to Angular’s normal provider system and makes the cache available through injection-based APIs.

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

import {
  provideTanStackQuery,
  QueryClient,
} from '@tanstack/angular-query-experimental'
 
bootstrapApplication(AppComponent, {
  providers: [provideTanStackQuery(new QueryClient())],
})

import {
  provideTanStackQuery,
  withDevtools,
  QueryClient,
} from '@tanstack/angular-query-experimental'
 
bootstrapApplication(AppComponent, {
  providers: [provideTanStackQuery(new QueryClient(), withDevtools())],
})

The InjectionToken form is useful when a team wants the client factory to live behind Angular dependency injection. The documentation positions this as an advanced lazy-loading optimization, not as the default recommendation. If Query is used throughout the application shell, configure the QueryClient in the main application providers so the cache is available consistently. If Query is only used behind a lazy route, an InjectionToken can defer the dependency and still provide a shared client for that lazy area. Be deliberate here: multiple clients mean multiple independent caches, so the provider boundary becomes part of your cache architecture.

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

Fetching with Angular HttpClient and Other Clients

Angular Query query functions must return promises because TanStack Query’s fetching mechanism is promise based. Angular HttpClient currently returns observables, so the Angular guide converts them with RxJS firstValueFrom or lastValueFrom inside queryFn. This preserves HttpClient benefits such as Angular testing support, interceptors integrated with dependency injection, pending task awareness for tests and server rendering, and built-in SSR request caching. The docs also note that TanStack Query has its own hydration functionality, so teams should choose between HttpClient SSR caching and Query hydration based on the requirements of their rendering flow.

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'),
      ),
  }))
}

The same guide compares HttpClient with fetch and specialized libraries such as graphql-request. Fetch keeps bundle impact low because it is browser native, but it lacks the Angular integration of HttpClient. Specialized clients may be attractive for a GraphQL or generated-client workflow, but if they are not Angular libraries they will not participate as deeply in Angular dependency injection and framework services. This is the core design tradeoff: TanStack Query does not care which asynchronous client produces the promise, but Angular applications may care a lot about how that client integrates with interceptors, tests, SSR, and application stability.

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

Devtools and Background Indicators

Angular devtools are enabled as a provider feature with withDevtools. The main devtools import is automatically excluded from production builds, and the documented production subpath exists for cases where a team intentionally wants to lazy load devtools in a production build or staging environment. The loadDevtools option accepts auto, true, or false through a callback. Auto loads only in Angular development mode, true permits loading in development and production, and false disables loading. The callback form is intentional because devtools options can be derived through reactivity, including signals that represent user shortcuts or environment decisions.

Sources: docs/framework/angular/devtools.md

import {
  QueryClient,
  provideTanStackQuery,
} from '@tanstack/angular-query-experimental'
import { withDevtools } from '@tanstack/angular-query-experimental/devtools'
 
export const appConfig: ApplicationConfig = {
  providers: [provideTanStackQuery(new QueryClient(), withDevtools())],
}

Background fetching indicators are separate from initial loading UI. The component example checks pending, error, and success states, then displays a refreshing message only when a successful query is fetching again. That distinction is important for Angular templates because it avoids replacing already available data with a full-page loading state during background refreshes. For application-wide activity, injectIsFetching gives a global count-like signal that can drive a top-level indicator. This pattern helps teams communicate that cached data is visible while fresh data is being requested, which is one of TanStack Query’s central UX advantages.

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

Compact API Reference

Next Steps

Start by wiring provideTanStackQuery once at the Angular application boundary, then build one component with injectQuery and a stable query key. If the project already standardizes on HttpClient, keep that integration and convert observables to promises inside queryFn until promise support is available. Add withDevtools during development so the team can inspect query keys, freshness, errors, and background activity. After the first screen works, read the background indicator guide to avoid confusing initial load with refetch state, then consult the broader TanStack Query guides for query keys, invalidation, mutations, hydration, and cache defaults.

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