snapshot of https://github.com/TanStack/query.git (main, 2026-09-16; blobs > 131072B omitted)

docs/framework/react/guides/window-focus-refetching.md

@@ -0,0 +1,111 @@
+---
+id: window-focus-refetching
+title: Window Focus Refetching
+---
+
+If a user leaves your application and returns and the query data is stale, **TanStack Query automatically requests fresh data for you in the background**. You can disable this globally or per-query using the `refetchOnWindowFocus` option:
+
+#### Disabling Globally
+
+[//]: # 'Example'
+
+```tsx
+//
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      refetchOnWindowFocus: false, // default: true
+    },
+  },
+})
+
+function App() {
+  return <QueryClientProvider client={queryClient}>...</QueryClientProvider>
+}
+```
+
+[//]: # 'Example'
+
+#### Disabling Per-Query
+
+[//]: # 'Example2'
+
+```tsx
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  refetchOnWindowFocus: false,
+})
+```
+
+[//]: # 'Example2'
+
+## Custom Window Focus Event
+
+In rare circumstances, you may want to manage your own window focus events that trigger TanStack Query to revalidate. To do this, TanStack Query provides a `focusManager.setEventListener` function that supplies you the callback that should be fired when the window is focused and allows you to set up your own events. When calling `focusManager.setEventListener`, the previously set handler is removed (which in most cases will be the default handler) and your new handler is used instead. For example, this is the default handler:
+
+[//]: # 'Example3'
+
+```tsx
+focusManager.setEventListener((handleFocus) => {
+  // Listen to visibilitychange
+  if (typeof window !== 'undefined' && window.addEventListener) {
+    const visibilitychangeHandler = () => {
+      handleFocus(document.visibilityState === 'visible')
+    }
+    window.addEventListener('visibilitychange', visibilitychangeHandler, false)
+    return () => {
+      // Be sure to unsubscribe if a new handler is set
+      window.removeEventListener('visibilitychange', visibilitychangeHandler)
+    }
+  }
+})
+```
+
+[//]: # 'Example3'
+[//]: # 'ReactNative'
+
+## Managing Focus in React Native
+
+Instead of event listeners on `window`, React Native provides focus information through the [`AppState` module](https://reactnative.dev/docs/appstate#app-states). You can use the `AppState` "change" event to trigger an update when the app state changes to "active":
+
+```tsx
+import { AppState } from 'react-native'
+import { focusManager } from '@tanstack/react-query'
+
+function onAppStateChange(status: AppStateStatus) {
+  if (Platform.OS !== 'web') {
+    focusManager.setFocused(status === 'active')
+  }
+}
+
+useEffect(() => {
+  const subscription = AppState.addEventListener('change', onAppStateChange)
+
+  return () => subscription.remove()
+}, [])
+```
+
+[//]: # 'ReactNative'
+
+## Managing focus state
+
+[//]: # 'Example4'
+
+```tsx
+import { focusManager } from '@tanstack/react-query'
+
+// Override the default focus state
+focusManager.setFocused(true)
+
+// Fallback to the default focus check
+focusManager.setFocused(undefined)
+```
+
+[//]: # 'Example4'
+
+## Troubleshooting
+
+If stale queries do not refetch when you return to a tab, check whether **Emulate a focused page** is enabled in Chrome DevTools. This setting keeps `document.visibilityState` set to `visible` and prevents `visibilitychange` events, which TanStack Query uses for its default focus handling.
+
+Disable **Emulate a focused page** in the DevTools **Rendering** panel, then switch to another tab and return to test window focus refetching. See the [Chrome DevTools documentation](https://developer.chrome.com/docs/devtools/rendering/apply-effects#emulate_a_focused_page) for more details.