Connect custom focus events
An app uses a platform lifecycle or custom event source instead of browser focus events.
TanStack · Const
focusManager
focusManager is TanStack Query's singleton focus-state controller. It lets you customize focus events, manually override focus, and inspect the current state.
How it works
The singleton focusManager controls the focus state observed by TanStack Query. Use setFocused for an explicit state, setFocused(undefined) to return to the default document-visibility check, or setEventListener to replace how focus changes are detected.
Syntax
const focusManager: FocusManager;Parameters
| Name | Type | Description |
|---|---|---|
setup | (setFocused: (focused?: boolean) => void) => () => void | Callback that installs custom focus detection and returns cleanup for the installed listener. |
focused | boolean | undefined | Explicit focus value; undefined restores the default focus check. |
Returns
focusManager is a singleton FocusManager instance; isFocused() returns the current focus state.
Key points
- focusManager centralizes the focus state that TanStack Query observes.
- It supports both replacing automatic event detection and directly overriding the state.
- Use setEventListener when the application's focus signal comes from events other than the default browser listeners.
- The setup callback gets a function that custom events can invoke to report focus.
- Call isFocused to read the currently effective focus value.
Common mistakes
- Leaving an explicit state in place prevents the normal focus check from being used; pass undefined to restore it.
- A custom event listener must return cleanup logic so the previous subscriptions are removed when another listener replaces it.
Example: Override and restore focus state
import { focusManager } from '@tanstack/react-query'
focusManager.setFocused(false)
// Later, restore the normal document-visibility check
focusManager.setFocused(undefined)
console.log(focusManager.isFocused())Temporarily overrides TanStack Query's focus state, then restores the default check and reads the current result.
When to use it
Temporarily override focus
A workflow must temporarily prevent focus-driven query activity.
Read focus status
Code needs to inspect the focus state currently seen by TanStack Query.
Interview questions
QWhat is focusManager used for?
focusManager is the singleton FocusManager instance used to manage and observe focus state in TanStack Query. It exposes methods for custom event handling, manual state changes, and reading the current state.
Follow-up: How would you integrate a non-browser lifecycle? Call setFocused with true or false from that lifecycle, and pass undefined when control should return to the default check.
QHow does setFocused behave?
setFocused manually sets the focus state. Passing true or false forces the corresponding state, while passing undefined restores the default focus check.
Follow-up: Why might setFocused(undefined) be necessary after a temporary override? Without it, the manual state remains authoritative instead of allowing the normal document-visibility check to determine focus.
QWhen would you use setEventListener?
setEventListener accepts setup code that receives a callback for reporting focus changes. The setup should register the callback with the desired events and return an unsubscribe function for cleanup.
Follow-up: What should happen when a second custom listener is installed? The first listener's cleanup must run so its event handlers do not remain active.
Related
FocusManagersetEventListenersetFocusedisFocused