The onlineManager is a singleton that manages network connectivity state and notifies subscribers when the online state changes. It listens to the browser’s online and offline events by default and can be customized with custom event listeners.
Import
import { onlineManager } from '@tanstack/query-core'
Methods
subscribe
Subscribe to online state changes.
subscribe(listener: (online: boolean) => void): () => void
listener
(online: boolean) => void
required
Callback function that will be called when the online state changes. Receives a boolean indicating whether the network is online.
Returns an unsubscribe function that removes the listener when called.
Example
const unsubscribe = onlineManager.subscribe((isOnline) => {
console.log('Network is', isOnline ? 'online' : 'offline')
})
// Later, unsubscribe
unsubscribe()
setEventListener
Set a custom event listener for online state changes. This allows you to customize how network connectivity is detected.
setEventListener(setup: SetupFn): void
A setup function that receives a setOnline callback and returns an optional cleanup function.Type signature:type SetupFn = (
setOnline: (online: boolean) => void
) => (() => void) | undefined
The setup function should call setOnline(true) when the network comes online and setOnline(false) when it goes offline.
Example
// Custom online detection for React Native
import NetInfo from '@react-native-community/netinfo'
onlineManager.setEventListener((setOnline) => {
return NetInfo.addEventListener((state) => {
setOnline(state.isConnected ?? false)
})
})
setOnline
Manually set the online state.
setOnline(online: boolean): void
The new online state. Pass true to indicate the network is online, false to indicate it’s offline.
Example
// Manually set the network as online
onlineManager.setOnline(true)
// Manually set the network as offline
onlineManager.setOnline(false)
isOnline
Get the current online state.
Returns true if the network is online, false otherwise.
Example
if (onlineManager.isOnline()) {
console.log('Network is currently online')
}
Default Behavior
By default, the onlineManager listens to the browser’s online and offline events to detect network connectivity changes. The manager starts with the assumption that the network is online (true).
In environments where window.addEventListener is not available (like React Native), you need to set up a custom event listener using setEventListener.
Use Cases
Custom Online Detection
You can provide custom online detection logic for different environments:
import { onlineManager } from '@tanstack/query-core'
import NetInfo from '@react-native-community/netinfo'
// React Native example
onlineManager.setEventListener((setOnline) => {
return NetInfo.addEventListener((state) => {
setOnline(state.isConnected ?? false)
})
})
Disable Automatic Online Refetching
You can prevent automatic refetching when the network reconnects:
// Disable online detection by always returning true
onlineManager.setEventListener(() => {
return () => {}
})
onlineManager.setOnline(true)
Advanced Online Detection
You can implement more sophisticated online detection:
import { onlineManager } from '@tanstack/query-core'
// Ping a server to verify actual connectivity
onlineManager.setEventListener((setOnline) => {
const checkOnline = async () => {
try {
await fetch('/api/health')
setOnline(true)
} catch {
setOnline(false)
}
}
// Check immediately
checkOnline()
// Check every 30 seconds
const interval = setInterval(checkOnline, 30000)
// Also listen to browser events
const onlineListener = () => setOnline(true)
const offlineListener = () => setOnline(false)
window.addEventListener('online', onlineListener)
window.addEventListener('offline', offlineListener)
return () => {
clearInterval(interval)
window.removeEventListener('online', onlineListener)
window.removeEventListener('offline', offlineListener)
}
})
Testing
In tests, you can control the online state manually:
import { onlineManager } from '@tanstack/query-core'
test('should refetch when coming back online', () => {
// Simulate going offline
onlineManager.setOnline(false)
// Simulate coming back online
onlineManager.setOnline(true)
})
Responding to Network Changes
You can subscribe to network changes to update your UI or trigger custom logic:
import { onlineManager } from '@tanstack/query-core'
const unsubscribe = onlineManager.subscribe((isOnline) => {
if (isOnline) {
showNotification('You are back online!')
} else {
showNotification('You are offline. Some features may not work.')
}
})