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

FocusManager.md

207 lines4.3 KB

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