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

FocusManager.md

206 lines4.3 KB

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