Network Mode

Purpose and Scope

Network mode is the policy that decides whether TanStack Query should start asynchronous work now, wait for connectivity, or let the query function attempt a cache-capable read before relying on the network. It belongs to the same server-state lifecycle that makes Query useful: data is remote, shared by many observers, cached, invalidated, retried, refetched, and sometimes intentionally stale. The public modes are commonly described as online, always, and offline first. Choosing among them is less about a component and more about the transport behind the query function.

For Angular readers, the available repository documentation shows the practical integration points around that decision. Applications install a QueryClient through the Angular provider function, query functions return Promises, templates observe pending, error, success, and fetching signals, and devtools expose the resulting cache state during development. Those pieces explain where network mode fits even when a single page is not configuring it directly: it is an option in the client-driven query system, while Angular components remain focused on declaring data requirements and rendering observable state. 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, docs/framework/angular/devtools.md

Use online for ordinary server-backed requests that should not repeatedly fail while the runtime is offline. Use always for operations that can succeed independently from the global online signal, such as a local database bridge, an in-memory transport, a native layer, or a test client. Use offline first when the first attempt may be satisfied by a service worker, browser cache, SSR transfer cache, or another local layer, but follow-up retry behavior should still respect offline conditions. In all cases, the query function contract stays promise based and the observer result remains the UI boundary.

Relevant Source Files

• docs/framework/angular/reference/functions/provideTanStackQuery.md - Defines the Angular provider entry point that installs a QueryClient and optional features, making client-level query behavior available to components.
• docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md - Explains the promise-based fetcher contract and shows how Angular HttpClient observables are converted for query functions.
• docs/framework/angular/guides/background-fetching-indicators.md - Shows how Angular templates distinguish first-load state from background fetching with query result signals and a global fetching indicator.
• docs/framework/angular/devtools.md - Documents Angular devtools setup, production loading controls, and reactive options for inspecting query and mutation state.
• docs/config.json - Places Angular documentation in the public docs structure alongside other framework sections, which helps readers find the related setup and guide pages.
• docs/community-resources.md - Lists community articles, media, and utilities such as generated clients and query-key tooling that influence cache and transport design.

Core Primitives

A QueryClient is the runtime owner of caches, defaults, and installed features. In Angular Query, the documented entry point is provideTanStackQuery, which accepts a QueryClient instance or an InjectionToken that provides one and returns Angular providers. That means network behavior should be thought of as part of the QueryClient configuration surface rather than as a separate Angular service that each component manually coordinates. The same provider call can also install optional features, so debugging and policy setup share one application-level integration point. Sources: docs/framework/angular/reference/functions/provideTanStackQuery.md

The query function is the transport boundary. The Angular data-fetching guide states that TanStack Query fetching is built agnostically on Promises, so the library does not require fetch, GraphQL, REST, or Angular HttpClient specifically. With HttpClient, observables need conversion through lastValueFrom or firstValueFrom before TanStack Query can manage the lifecycle. That conversion is important for network mode because Query can pause, retry, notify observers, and cache results around a single Promise contract while the chosen client still owns authentication, interceptors, testing behavior, SSR integration, and protocol details. Sources: docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

Managers are the environmental bridge that make network mode operational. The online signal answers whether work that depends on connectivity should run, while focus and background activity signals influence when existing data is refreshed. A component should not usually render a full-page loading state every time a background refetch happens. The Angular guide demonstrates that distinction by rendering a pending branch for the first load, an error branch for failures, successful data when available, and a separate refreshing message when the query is fetching in the background. Sources: docs/framework/angular/guides/background-fetching-indicators.md

Network Mode Semantics

Online is the conservative choice for normal remote data. If the application is considered offline, starting a request that needs the network often produces a noisy failure rather than useful information. With online behavior, Query can coordinate execution with the connectivity manager and let the observer communicate that work is pending, paused, or fetching according to the adapter’s state model. In Angular templates, this pairs naturally with separate handling for first load and background refresh: the useful cached result can remain visible while a small indicator explains that a refetch is in progress or waiting for better conditions.

Always is a deliberate opt out of connectivity gating. It says the query or mutation function should be allowed to run even when the global online signal reports offline. That can be correct when the operation talks to a local database, a native mobile bridge, an embedded worker, a deterministic test double, or another resource whose success is not represented by browser connectivity. Always does not make failures disappear and it does not change cache identity. The Promise still resolves or rejects, retries still depend on the configured retry policy, and observers still receive status and fetching information.

Offline first is useful when the first attempt has a meaningful local path. A service worker, HTTP cache, Angular SSR HttpClient cache, or application storage layer may be able to return data before a network request is necessary. If that first path cannot satisfy the read and the device is offline, repeated network retries can waste time and produce confusing UI. Offline-first behavior fits those cache-capable transports because it lets the query function try its best local strategy while still allowing TanStack Query to cooperate with offline detection for later attempts. Sources: docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

Angular Execution Flow

A typical Angular setup starts in application configuration. The reference page shows standalone bootstrapping with provideTanStackQuery(new QueryClient()) and an NgModule provider variant with the same provider call. It also documents an InjectionToken form for lazy-loaded routes or lazy-loaded components, which can keep TanStack Query out of the main application bundle while still sharing a QueryClient. That setup decision matters for network mode because defaults are easiest to reason about when the owning QueryClient is created in one intentional place rather than scattered across unrelated components. Sources: docs/framework/angular/reference/functions/provideTanStackQuery.md

After the provider is installed, a component declares its data dependency with a query key and a query function. The HttpClient example injects Angular HttpClient, calls injectQuery, uses a stable key, and returns a Promise converted from http.get. Network mode then answers when that Promise should be started or retried; it does not replace the HTTP client. This separation lets Angular teams keep familiar interceptors, mock responses in unit tests, pending-task awareness, and SSR request caching while still gaining Query’s cache lifecycle, deduplication, invalidation, and observer updates. Sources: docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

The rendering step should preserve user context. The background fetching guide shows a component that renders loading only while the query is pending, renders an error message when the query is in error state, and renders successful data while optionally showing a refreshing indicator. That pattern is especially important with offline-aware behavior. If cached data is already present, losing it during a refetch can make the application feel broken even though the cache is doing useful work. A global indicator built with injectIsFetching can also show background activity outside individual feature components. Sources: docs/framework/angular/guides/background-fetching-indicators.md

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

readonly query = injectQuery(() => ({
  queryKey: ['repoData'],
  queryFn: () =>
    lastValueFrom(
      this.http.get('https://api.github.com/repos/tanstack/query'),
    ),
  networkMode: 'online',
}))

API and Configuration Reference

Do not choose a network mode only because a screen is important or unimportant. Start with the fetcher’s real capabilities. A REST endpoint that must reach a remote server should normally use online behavior and clear offline or retry UX. A generated GraphQL client still usually needs the same treatment unless it has a cache layer that can answer independently. A storage-backed query or native bridge may be better represented by always. A service-worker-backed request, SSR cache handoff, or browser cache strategy may justify offline first because the first attempt can provide useful data without immediate connectivity.

Debugging and Operational Signals

Devtools are the best way to verify that the chosen policy matches runtime behavior. The Angular devtools guide enables them by passing withDevtools to provideTanStackQuery, and it notes that the devtools are only included in development mode bundles by default. For staging or production-like diagnostics, the production subpath and loadDevtools option allow explicit or reactive loading. This matters for network behavior because a paused query, a background refetch, and a rejected Promise can look similar in the UI unless the cache, observers, status, and fetching state are visible. Sources: docs/framework/angular/devtools.md, docs/framework/angular/reference/functions/provideTanStackQuery.md

The public documentation structure and community resources also help teams make durable choices around network behavior. The docs config places Angular alongside the other framework sections, so readers can move between setup, guides, and reference material without treating Angular Query as a separate product. The community resources page points to maintainer writing, talks, query-key factories, GraphQL code generation, OpenAPI client generation, batching utilities, and visualization tools. Those resources do not define network mode, but they influence how teams design query keys, generated clients, retries, and cache boundaries around offline or flaky transports. Sources: docs/config.json, docs/community-resources.md

Next Steps

When adopting network mode, audit each data source before changing application defaults. Identify whether the query function truly needs a live network, whether it can return from a local cache, and whether retries should wait for connectivity. Centralize broad defaults where the QueryClient is provided, override individual queries when their transport differs, and keep Angular templates honest by distinguishing pending, success, error, and background fetching states. Then enable devtools during development or staging to confirm that the cache and observers behave the way the user interface suggests.

Related pages to read next are query-functions for the Promise-based fetcher contract, background-refetching for user-facing refresh behavior, retries-and-cancellation for retry and abort details, angular-query-experimental for Angular-specific primitives, and devtools for inspection workflows.