Default browser connectivity
A browser application needs TanStack Query to react to normal connectivity changes.
TanStack · Const
onlineManager
onlineManager is TanStack Query's singleton controller for application connectivity. It reads browser online/offline events by default and supports custom listeners or manual state changes.
How it works
The singleton tracks whether TanStack Query considers the application connected. It normally derives this from browser online and offline events, but you can replace that detection with a custom listener or directly override the state.
Syntax
const onlineManager: OnlineManager;Parameters
| Name | Type | Description |
|---|---|---|
online | boolean | undefined | The boolean connectivity value supplied to setOnline; the API also supports undefined for the default check. |
setup | (setOnline: (online: boolean) => void) => (() => void) | A setup function that receives setOnline and returns listener cleanup. |
Returns
Singleton OnlineManager instance; isOnline returns boolean and listener-registration status returns boolean.
Key points
- The object centralizes the connectivity state consumed by TanStack Query.
- In a browser, its default detector responds to window connectivity events.
- Call isOnline when code needs the current connectivity decision.
- Use setOnline to explicitly mark the application online or offline.
- Use setEventListener when the default browser detector does not match the runtime.
- The listener-registration status method reports whether listeners remain active.
Common mistakes
- The initial assumption is that the application is online until connectivity detection changes it.
- A custom event listener must invoke the supplied callback whenever connectivity changes.
Example: Control the online state
import { onlineManager } from '@tanstack/react-query'
onlineManager.setOnline(false)
console.log(onlineManager.isOnline())
onlineManager.setOnline(true)Manually toggles TanStack Query's connectivity state and reads it back.
When to use it
Platform-specific network detection
A React Native or other non-browser runtime provides its own network-status subscription.
Manual connectivity control
Tests or application infrastructure need to force online or offline behavior.
Interview questions
QWhat is onlineManager used for?
onlineManager is the singleton OnlineManager used to manage and observe TanStack Query's online state. It exposes methods for querying the state, overriding it, and installing custom detection.
Follow-up: How would you support React Native connectivity? Install a platform network listener and pass its connection status to the callback received by setEventListener.
QHow do you read the current online state?
Call onlineManager.isOnline() to read the current status. It returns a boolean, with true meaning TanStack Query currently considers the app online.
Follow-up: What should code do when the status changes? Use setOnline through the configured listener so TanStack Query receives each new boolean state.
QHow can custom connectivity detection be configured?
Use onlineManager.setEventListener to replace the default browser event handling. Its setup function receives setOnline, and the setup function should return cleanup for the installed listener.
Follow-up: When is direct setOnline useful? It is useful when application code already knows connectivity or must manually force the state during testing or specialized runtime integration.
Related
OnlineManagerisOnlinesetEventListenersetOnline