diff --git a/README.md b/README.md
index cc1728fafd..4da9ce2a19 100644
--- a/README.md
+++ b/README.md
@@ -65,6 +65,7 @@
- [`useScroll`](./docs/useScroll.md) — tracks an HTML element's scroll position. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usescroll--docs)
- [`useScrolling`](./docs/useScrolling.md) — tracks whether HTML element is scrolling.
- [`useStartTyping`](./docs/useStartTyping.md) — detects when user starts typing.
+ - [`useWindowFocus`](./docs/useWindowFocus.md) — tracks whether the browser window is focused. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usewindowfocus--demo)
- [`useWindowScroll`](./docs/useWindowScroll.md) — tracks `Window` scroll position. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usewindowscroll--docs)
- [`useWindowSize`](./docs/useWindowSize.md) — tracks `Window` dimensions. [![][img-demo]](https://codesandbox.io/s/m7ln22668)
- [`useMeasure`](./docs/useMeasure.md) and [`useSize`](./docs/useSize.md) — tracks an HTML element's dimensions. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usemeasure--demo)
diff --git a/docs/useWindowFocus.md b/docs/useWindowFocus.md
new file mode 100644
index 0000000000..abdfa28443
--- /dev/null
+++ b/docs/useWindowFocus.md
@@ -0,0 +1,29 @@
+# `useWindowFocus`
+
+React sensor hook that tracks if the browser window is focused.
+
+## Usage
+
+```jsx
+import {useWindowFocus} from 'react-use';
+
+const Demo = () => {
+ const defaultState = document.hasFocus();
+ const isFocused = useWindowFocus(defaultState);
+
+ return (
+
+ Window is {isFocused ? 'focused' : 'not focused'}
+
+ );
+};
+```
+
+## Reference
+
+```js
+const isFocused = useWindowFocus(initialState);
+```
+
+- `initialState` — `boolean`, optional initial state before the actual focus is determined, defaults to `false`.
+- `isFocused` — `boolean`, whether the browser window is currently focused.
diff --git a/src/index.ts b/src/index.ts
index 62b69356b7..464d9af55d 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -106,6 +106,7 @@ export { default as useVideo } from './useVideo';
export { default as useStateValidator } from './useStateValidator';
export { useScrollbarWidth } from './useScrollbarWidth';
export { useMultiStateValidator } from './useMultiStateValidator';
+export { default as useWindowFocus } from './useWindowFocus';
export { default as useWindowScroll } from './useWindowScroll';
export { default as useWindowSize } from './useWindowSize';
export { default as useMeasure } from './useMeasure';
diff --git a/src/useWindowFocus.ts b/src/useWindowFocus.ts
new file mode 100644
index 0000000000..8109cfdc64
--- /dev/null
+++ b/src/useWindowFocus.ts
@@ -0,0 +1,22 @@
+import { useEffect, useState } from 'react';
+
+const useWindowFocus = (defaultState: boolean = false) => {
+ const [isFocused, setIsFocused] = useState(defaultState);
+
+ useEffect(() => {
+ const handleFocus = () => setIsFocused(true);
+ const handleBlur = () => setIsFocused(false);
+
+ window.addEventListener('focus', handleFocus);
+ window.addEventListener('blur', handleBlur);
+
+ return () => {
+ window.removeEventListener('focus', handleFocus);
+ window.removeEventListener('blur', handleBlur);
+ };
+ }, []);
+
+ return isFocused;
+};
+
+export default useWindowFocus;
diff --git a/stories/useWindowFocus.story.tsx b/stories/useWindowFocus.story.tsx
new file mode 100644
index 0000000000..f662cd537a
--- /dev/null
+++ b/stories/useWindowFocus.story.tsx
@@ -0,0 +1,22 @@
+import { storiesOf } from '@storybook/react';
+import * as React from 'react';
+import useWindowFocus from '../src/useWindowFocus';
+import ShowDocs from './util/ShowDocs';
+
+const Demo = () => {
+ const defaultState = document.hasFocus();
+ const isFocused = useWindowFocus(defaultState);
+
+ return (
+
+
Click outside this window or switch to another tab to see the focus state change.
+
+ Window is {isFocused ? '✅ Focused' : '❌ Not Focused'}
+
+
+ );
+};
+
+storiesOf('Sensors/useWindowFocus', module)
+ .add('Docs', () => )
+ .add('Demo', () => );
diff --git a/tests/useWindowFocus.test.ts b/tests/useWindowFocus.test.ts
new file mode 100644
index 0000000000..b2ba70eaaa
--- /dev/null
+++ b/tests/useWindowFocus.test.ts
@@ -0,0 +1,91 @@
+import { renderHook, act } from '@testing-library/react-hooks';
+import useWindowFocus from '../src/useWindowFocus';
+
+describe('useWindowFocus', () => {
+ it('should be defined', () => {
+ expect(useWindowFocus).toBeDefined();
+ });
+
+ it('should return false initially', () => {
+ const { result } = renderHook(() => useWindowFocus());
+
+ expect(result.current).toBe(false);
+ });
+
+ it('should return true initially when defaultState is true', () => {
+ const { result } = renderHook(() => useWindowFocus(true));
+
+ expect(result.current).toBe(true);
+ });
+
+ it('should return false initially when defaultState is false', () => {
+ const { result } = renderHook(() => useWindowFocus(false));
+
+ expect(result.current).toBe(false);
+ });
+
+ it('should return true when window receives focus', () => {
+ const { result } = renderHook(() => useWindowFocus());
+
+ act(() => {
+ window.dispatchEvent(new Event('focus'));
+ });
+
+ expect(result.current).toBe(true);
+ });
+
+ it('should return false when window loses focus', () => {
+ const { result } = renderHook(() => useWindowFocus());
+
+ act(() => {
+ window.dispatchEvent(new Event('focus'));
+ });
+ expect(result.current).toBe(true);
+
+ act(() => {
+ window.dispatchEvent(new Event('blur'));
+ });
+ expect(result.current).toBe(false);
+ });
+
+ it('should add event listeners on mount', () => {
+ const addEventListenerSpy = jest.spyOn(window, 'addEventListener');
+
+ renderHook(() => useWindowFocus());
+
+ expect(addEventListenerSpy).toHaveBeenCalledWith('focus', expect.any(Function));
+ expect(addEventListenerSpy).toHaveBeenCalledWith('blur', expect.any(Function));
+
+ addEventListenerSpy.mockRestore();
+ });
+
+ it('should remove the same event listeners on unmount', () => {
+ const addEventListenerSpy = jest.spyOn(window, 'addEventListener');
+ const removeEventListenerSpy = jest.spyOn(window, 'removeEventListener');
+
+ const { unmount } = renderHook(() => useWindowFocus());
+ const getHandler = (spy: jest.SpyInstance, type: string) =>
+ spy.mock.calls.find(([eventType]) => eventType === type)?.[1];
+ const focusHandler = getHandler(addEventListenerSpy, 'focus');
+ const blurHandler = getHandler(addEventListenerSpy, 'blur');
+
+ unmount();
+
+ expect(removeEventListenerSpy).toHaveBeenCalledWith('focus', focusHandler);
+ expect(removeEventListenerSpy).toHaveBeenCalledWith('blur', blurHandler);
+
+ addEventListenerSpy.mockRestore();
+ removeEventListenerSpy.mockRestore();
+ });
+
+ it('should stop updating after unmount', () => {
+ const { result, unmount } = renderHook(() => useWindowFocus());
+
+ unmount();
+ act(() => {
+ window.dispatchEvent(new Event('focus'));
+ });
+
+ expect(result.current).toBe(false);
+ });
+});