Skip to main content

​
OnlineManager

Manages online/offline network state and notifies subscribers when the network state changes. This is used by TanStack Query to automatically pause and resume queries based on network availability. 
import { onlineManager } from '@tanstack/query-core'

​
Instance

A singleton instance is exported as onlineManager: 
export const onlineManager = new OnlineManager()

​
Methods

​
setEventListener

Sets up a custom event listener for online/offline events. 
setEventListener(setup: SetupFn): void
​
setup
SetupFn
required
A function that sets up online/offline event listeners. The setup function receives a setOnline callback and should return a cleanup function.Type definition:
type SetupFn = (setOnline: (online: boolean) => void) => (() => void) | undefined
Parameters:
  • setOnline - Callback to notify the manager of network state changes. Call with true when online, false when offline.
Returns:
  • A cleanup function that will be called when the event listener is removed or replaced
Usage: 
import { onlineManager } from '@tanstack/query-core'
import NetInfo from '@react-native-community/netinfo'

// Custom network detection for React Native
onlineManager.setEventListener((setOnline) => {
  const unsubscribe = NetInfo.addEventListener((state) => {
    setOnline(!!state.isConnected)
  })

  return () => {
    unsubscribe()
  }
})
Default behavior: By default, the OnlineManager listens to online and offline events on the window: 
const onlineListener = () => setOnline(true)
const offlineListener = () => setOnline(false)

window.addEventListener('online', onlineListener, false)
window.addEventListener('offline', offlineListener, false)

return () => {
  window.removeEventListener('online', onlineListener)
  window.removeEventListener('offline', offlineListener)
}

​
setOnline

Manually sets the online state. 
setOnline(online: boolean): void
​
online
boolean
required
The new online state. true indicates the network is available, false indicates offline.
Usage: 
import { onlineManager } from '@tanstack/query-core'

// Manually set online state
onlineManager.setOnline(false) // Simulate offline

// Later: go back online
onlineManager.setOnline(true)
Behavior:
  • Only notifies listeners if the online state has actually changed
  • All subscribed listeners are notified of the new state
  • This is automatically called by the event listener setup function

​
subscribe

Subscribes to online/offline state changes. 
subscribe(listener: Listener): () => void
​
listener
(online: boolean) => void
required
A callback function that will be called whenever the online state changes. The callback receives a boolean indicating whether the network is currently online.
Returns: An unsubscribe function that removes the listener when called. Usage: 
import { onlineManager } from '@tanstack/query-core'

// Subscribe to online/offline changes
const unsubscribe = onlineManager.subscribe((isOnline) => {
  if (isOnline) {
    console.log('Network is online - resuming queries')
  } else {
    console.log('Network is offline - pausing queries')
  }
})

// Later: unsubscribe
unsubscribe()
Behavior:
  • Automatically sets up the event listener on the first subscription
  • Cleans up the event listener when the last subscriber unsubscribes
  • Multiple listeners can be added simultaneously
  • Each listener is called with the current online state when it changes

​
isOnline

Returns the current online state. 
isOnline(): boolean
Returns: true if the network is currently online, false otherwise. Usage: 
import { onlineManager } from '@tanstack/query-core'

if (onlineManager.isOnline()) {
  console.log('Network is available')
  // Proceed with network request
} else {
  console.log('Network is offline')
  // Show offline message
}
Behavior:
  • Returns the current internal online state
  • Defaults to true (online) when the OnlineManager is first created
  • Can be manually updated via setOnline() or automatically via event listeners

​
Complete Example

import { onlineManager } from '@tanstack/query-core'

// Subscribe to network state changes
const unsubscribe = onlineManager.subscribe((isOnline) => {
  if (isOnline) {
    console.log('Back online - syncing data')
    syncPendingChanges()
  } else {
    console.log('Gone offline - enabling offline mode')
    enableOfflineMode()
  }
})

// Check current network state
if (!onlineManager.isOnline()) {
  showOfflineIndicator()
}

// Manually trigger an offline state (useful for testing)
onlineManager.setOnline(false)

// Custom network detection for React Native
onlineManager.setEventListener((setOnline) => {
  const unsubscribe = NetInfo.addEventListener((state) => {
    setOnline(state.isConnected && state.isInternetReachable)
  })

  return unsubscribe
})

// Clean up when done
unsubscribe()

​
Testing Example

import { onlineManager } from '@tanstack/query-core'
import { renderHook } from '@testing-library/react'
import { useQuery } from '@tanstack/react-query'

test('queries pause when offline', async () => {
  // Mock offline state
  onlineManager.setOnline(false)

  const { result } = renderHook(() =>
    useQuery({
      queryKey: ['data'],
      queryFn: fetchData,
    })
  )

  // Query should be paused
  expect(result.current.isPaused).toBe(true)

  // Go back online
  onlineManager.setOnline(true)

  // Query should resume
  await waitFor(() => expect(result.current.isSuccess).toBe(true))
})

​
Integration with TanStack Query

The OnlineManager is used internally by TanStack Query to implement network-aware query behavior: 
import { useQuery } from '@tanstack/react-query'

const query = useQuery({
  queryKey: ['data'],
  queryFn: fetchData,
  // Retry when going back online (default: true)
  refetchOnReconnect: true,
  // Pause queries when offline (default: true for queries, false for mutations)
  networkMode: 'online',
})

​
Network Modes

TanStack Query uses the OnlineManager to support different network modes:
  • online - Queries/mutations pause when offline
  • always - Queries/mutations run regardless of online state
  • offlineFirst - Queries/mutations run, but failures are retried when back online

​
Platform Support

  • Browser: Uses online and offline events by default
  • React Native: Requires custom setup with NetInfo or similar
  • Node.js: Always returns true by default (no network detection)

​
Type Definitions

type Listener = (online: boolean) => void

type SetupFn = (setOnline: (online: boolean) => void) => (() => void) | undefined

class OnlineManager extends Subscribable<Listener> {
  setEventListener(setup: SetupFn): void
  setOnline(online: boolean): void
  subscribe(listener: Listener): () => void
  isOnline(): boolean
}

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us