diff --git a/README.md b/README.md
index cc1728fafd..8a49102433 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,7 @@
- [**Sensors**](./docs/Sensors.md)
- [`useBattery`](./docs/useBattery.md) — tracks device battery state. [![][img-demo]](https://codesandbox.io/s/qlvn662zww)
+ - [`useDocumentVisibility`](./docs/useDocumentVisibility.md) — tracks whether the document is visible (Page Visibility API). [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usedocumentvisibility--demo)
- [`useGeolocation`](./docs/useGeolocation.md) — tracks geo location state of user's device. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usegeolocation--demo)
- [`useHover` and `useHoverDirty`](./docs/useHover.md) — tracks mouse hover state of some element. [![][img-demo]](https://codesandbox.io/s/zpn583rvx)
- [`useHash`](./docs/useHash.md) — tracks location hash value. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usehash--demo)
diff --git a/docs/useDocumentVisibility.md b/docs/useDocumentVisibility.md
new file mode 100644
index 0000000000..4ffb1a16bc
--- /dev/null
+++ b/docs/useDocumentVisibility.md
@@ -0,0 +1,29 @@
+# `useDocumentVisibility`
+
+React sensor hook that tracks document visibility state using the [Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API).
+
+## Usage
+
+```jsx
+import {useDocumentVisibility} from 'react-use';
+
+const Demo = () => {
+ const defaultState = document.visibilityState === 'visible';
+ const isVisible = useDocumentVisibility(defaultState);
+
+ return (
+
+ Document is {isVisible ? 'visible' : 'hidden'}
+
+ );
+};
+```
+
+## Reference
+
+```js
+const isVisible = useDocumentVisibility(initialState);
+```
+
+- `initialState` — `boolean`, optional initial state before the actual visibility is determined, defaults to `false`.
+- `isVisible` — `boolean`, whether the document is currently visible (tab is in foreground).
diff --git a/src/index.ts b/src/index.ts
index 62b69356b7..42981a6394 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -18,6 +18,7 @@ export { default as useCustomCompareEffect } from './useCustomCompareEffect';
export { default as useDebounce } from './useDebounce';
export { default as useDeepCompareEffect } from './useDeepCompareEffect';
export { default as useDefault } from './useDefault';
+export { default as useDocumentVisibility } from './useDocumentVisibility';
export { default as useDrop } from './useDrop';
export { default as useDropArea } from './useDropArea';
export { default as useEffectOnce } from './useEffectOnce';
diff --git a/src/useDocumentVisibility.ts b/src/useDocumentVisibility.ts
new file mode 100644
index 0000000000..1f7b7f1ae8
--- /dev/null
+++ b/src/useDocumentVisibility.ts
@@ -0,0 +1,19 @@
+import { useEffect, useState } from 'react';
+
+const useDocumentVisibility = (defaultState: boolean = false) => {
+ const [isVisible, setIsVisible] = useState(defaultState);
+
+ useEffect(() => {
+ const handleVisibilityChange = () => setIsVisible(document.visibilityState === 'visible');
+
+ document.addEventListener('visibilitychange', handleVisibilityChange);
+
+ return () => {
+ document.removeEventListener('visibilitychange', handleVisibilityChange);
+ };
+ }, []);
+
+ return isVisible;
+};
+
+export default useDocumentVisibility;
diff --git a/stories/useDocumentVisibility.story.tsx b/stories/useDocumentVisibility.story.tsx
new file mode 100644
index 0000000000..c97396c565
--- /dev/null
+++ b/stories/useDocumentVisibility.story.tsx
@@ -0,0 +1,22 @@
+import { storiesOf } from '@storybook/react';
+import * as React from 'react';
+import useDocumentVisibility from '../src/useDocumentVisibility';
+import ShowDocs from './util/ShowDocs';
+
+const Demo = () => {
+ const defaultState = document.visibilityState === 'visible';
+ const isVisible = useDocumentVisibility(defaultState);
+
+ return (
+
+
Switch to another browser tab to see the visibility state change.
+
+ Document is {isVisible ? '👁️ Visible' : '🙈 Hidden'}
+
+
+ );
+};
+
+storiesOf('Sensors/useDocumentVisibility', module)
+ .add('Docs', () => )
+ .add('Demo', () => );
diff --git a/tests/useDocumentVisibility.test.ts b/tests/useDocumentVisibility.test.ts
new file mode 100644
index 0000000000..0531fe0fa7
--- /dev/null
+++ b/tests/useDocumentVisibility.test.ts
@@ -0,0 +1,113 @@
+import { renderHook, act } from '@testing-library/react-hooks';
+import useDocumentVisibility from '../src/useDocumentVisibility';
+
+type VisibilityState = 'visible' | 'hidden';
+
+const setVisibilityState = (state: VisibilityState) => {
+ Object.defineProperty(document, 'visibilityState', {
+ configurable: true,
+ value: state,
+ });
+ document.dispatchEvent(new Event('visibilitychange'));
+};
+
+describe('useDocumentVisibility', () => {
+ afterEach(() => {
+ // Remove the own-property override so the native getter is used again
+ delete (document as { visibilityState?: VisibilityState }).visibilityState;
+ });
+
+ it('should be defined', () => {
+ expect(useDocumentVisibility).toBeDefined();
+ });
+
+ it('should return false initially', () => {
+ const { result } = renderHook(() => useDocumentVisibility());
+
+ expect(result.current).toBe(false);
+ });
+
+ it('should return true initially when initialState is true', () => {
+ const { result } = renderHook(() => useDocumentVisibility(true));
+
+ expect(result.current).toBe(true);
+ });
+
+ it('should return false initially when initialState is false', () => {
+ const { result } = renderHook(() => useDocumentVisibility(false));
+
+ expect(result.current).toBe(false);
+ });
+
+ it('should return true when document becomes visible', () => {
+ const { result } = renderHook(() => useDocumentVisibility(false));
+
+ act(() => {
+ setVisibilityState('visible');
+ });
+
+ expect(result.current).toBe(true);
+ });
+
+ it('should return false when document becomes hidden', () => {
+ const { result } = renderHook(() => useDocumentVisibility(true));
+
+ act(() => {
+ setVisibilityState('hidden');
+ });
+
+ expect(result.current).toBe(false);
+ });
+
+ it('should track multiple visibility changes', () => {
+ const { result } = renderHook(() => useDocumentVisibility());
+
+ act(() => {
+ setVisibilityState('visible');
+ });
+ expect(result.current).toBe(true);
+
+ act(() => {
+ setVisibilityState('hidden');
+ });
+ expect(result.current).toBe(false);
+ });
+
+ it('should add event listener on mount', () => {
+ const addEventListenerSpy = jest.spyOn(document, 'addEventListener');
+
+ renderHook(() => useDocumentVisibility());
+
+ expect(addEventListenerSpy).toHaveBeenCalledWith('visibilitychange', expect.any(Function));
+
+ addEventListenerSpy.mockRestore();
+ });
+
+ it('should remove the same event listener on unmount', () => {
+ const addEventListenerSpy = jest.spyOn(document, 'addEventListener');
+ const removeEventListenerSpy = jest.spyOn(document, 'removeEventListener');
+
+ const { unmount } = renderHook(() => useDocumentVisibility());
+ const handler = addEventListenerSpy.mock.calls.find(
+ ([type]) => type === 'visibilitychange'
+ )?.[1];
+
+ unmount();
+
+ expect(removeEventListenerSpy).toHaveBeenCalledWith('visibilitychange', handler);
+
+ addEventListenerSpy.mockRestore();
+ removeEventListenerSpy.mockRestore();
+ });
+
+ it('should stop updating after unmount', () => {
+ const { result, unmount } = renderHook(() => useDocumentVisibility());
+
+ unmount();
+ act(() => {
+ setVisibilityState('visible');
+ });
+
+ expect(result.current).toBe(false);
+ });
+});