Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

FocusManager.md

204 lines4.2 KB

1---
2id: FocusManager
3title: FocusManager
4---
5​
6Defined in: [packages/query-core/src/focusManager.ts:14](https://github.com/TanStack/query/blob/main/packages/query-core/src/focusManager.ts#L14)
7​
8The `FocusManager` manages the focus state within TanStack Query.
9​
10It can be used to change the default event listeners or to manually change the focus state.
11​
12## Extends
13​
14- `Subscribable`\<`Listener`\>
15​
16## Methods
17​
18### hasListeners()
19​
20```ts
21hasListeners(): boolean;
22```
23​
24Defined in: [packages/query-core/src/subscribable.ts:43](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L43)
25​
26Returns `true` while at least one listener is registered, `false` once they have all unsubscribed.
27​
28#### Returns
29​
30`boolean`
31​
32`true` if at least one listener is registered.
33​
34#### Inherited from
35​
36```ts
37Subscribable.hasListeners
38```
39​
40***
41​
42### isFocused()
43​
44```ts
45isFocused(): boolean;
46```
47​
48Defined in: [packages/query-core/src/focusManager.ts:130](https://github.com/TanStack/query/blob/main/packages/query-core/src/focusManager.ts#L130)
49​
50`isFocused` can be used to get the current focus state.
51​
52#### Returns
53​
54`boolean`
55​
56The focus state set with `setFocused`, or otherwise whether the document is visible.
57​
58***
59​
60### onFocus()
61​
62```ts
63onFocus(): void;
64```
65​
66Defined in: [packages/query-core/src/focusManager.ts:119](https://github.com/TanStack/query/blob/main/packages/query-core/src/focusManager.ts#L119)
67​
68`onFocus` notifies all subscribed listeners with the current focus state.
69​
70#### Returns
71​
72`void`
73​
74***
75​
76### setEventListener()
77​
78```ts
79setEventListener(setup: SetupFn): void;
80```
81​
82Defined in: [packages/query-core/src/focusManager.ts:78](https://github.com/TanStack/query/blob/main/packages/query-core/src/focusManager.ts#L78)
83​
84`setEventListener` can be used to set a custom event listener that will
85be used to determine the focus state. The provided `setup` function
86receives a `setFocused` callback: call it with a `boolean` to manually
87set the focus state, or with no arguments to re-evaluate the current
88focus state and notify subscribers.
89​
90#### Parameters
91​
92##### setup
93​
94`SetupFn`
95​
96Receives the `setFocused` callback, registers the event listener, and may return
97a cleanup function that is called when the listener is replaced or no longer needed.
98​
99#### Returns
100​
101`void`
102​
103#### Example
104​
105```ts
106import { focusManager } from '@tanstack/query-core'
107​
108focusManager.setEventListener((handleFocus) => {
109 const listener = () => handleFocus()
110 // Listen to visibilitychange
111 if (typeof window !== 'undefined' && window.addEventListener) {
112 window.addEventListener('visibilitychange', listener, false)
113 }
114​
115 return () => {
116 // Be sure to unsubscribe if a new handler is set
117 window.removeEventListener('visibilitychange', listener)
118 }
119})
120```
121​
122***
123​
124### setFocused()
125​
126```ts
127setFocused(focused?: boolean): void;
128```
129​
130Defined in: [packages/query-core/src/focusManager.ts:108](https://github.com/TanStack/query/blob/main/packages/query-core/src/focusManager.ts#L108)
131​
132`setFocused` can be used to manually set the focus state. Set `undefined`
133to fall back to the default focus check.
134​
135#### Parameters
136​
137##### focused?
138​
139`boolean`
140​
141The focus state, or `undefined` to use the default focus check.
142​
143#### Returns
144​
145`void`
146​
147#### Example
148​
149```ts
150import { focusManager } from '@tanstack/query-core'
151​
152// Set focused
153focusManager.setFocused(true)
154​
155// Set unfocused
156focusManager.setFocused(false)
157​
158// Fallback to the default focus check
159focusManager.setFocused(undefined)
160```
161​
162***
163​
164### subscribe()
165​
166```ts
167subscribe(listener: Listener): () => void;
168```
169​
170Defined in: [packages/query-core/src/subscribable.ts:28](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L28)
171​
172Registers a listener to be called on every update this object notifies about. Returns a function
173that removes the listener again β€” call it to stop listening. The base class never drops a listener
174on its own, though some subclasses clear all of theirs in `destroy()`.
175​
176#### Parameters
177​
178##### listener
179​
180`Listener`
181​
182Called on each update, with whatever the subclass passes to its subscribers.
183​
184#### Returns
185​
186A function that removes the listener.
187​
188() => `void`
189​
190#### Example
191​
192```ts
193const unsubscribe = subscribable.subscribe(() => {
194 // react to the update
195})
196​
197unsubscribe()
198```
199​
200#### Inherited from
201​
202```ts
203Subscribable.subscribe
204```