From 2307ee9ea48ed7fc7fcdf0d2477d35edc6bc4a37 Mon Sep 17 00:00:00 2001 From: lukKowalski Date: Thu, 12 Feb 2026 22:33:22 +0100 Subject: [PATCH 1/3] feat: Added new hook - useDocumentVisibility --- docs/useDocumentVisibility.md | 29 ++++++++ src/index.ts | 1 + src/useDocumentVisibility.ts | 19 +++++ stories/useDocumentVisibility.story.tsx | 22 ++++++ tests/useDocumentVisibility.test.ts | 92 +++++++++++++++++++++++++ 5 files changed, 163 insertions(+) create mode 100644 docs/useDocumentVisibility.md create mode 100644 src/useDocumentVisibility.ts create mode 100644 stories/useDocumentVisibility.story.tsx create mode 100644 tests/useDocumentVisibility.test.ts 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..5ddc0ed09d --- /dev/null +++ b/tests/useDocumentVisibility.test.ts @@ -0,0 +1,92 @@ +import { renderHook, act } from '@testing-library/react-hooks'; +import useDocumentVisibility from '../src/useDocumentVisibility'; + +describe('useDocumentVisibility', () => { + const originalVisibilityState = document.visibilityState; + + afterEach(() => { + Object.defineProperty(document, 'visibilityState', { + configurable: true, + value: originalVisibilityState, + }); + }); + + 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(true)); + + act(() => { + Object.defineProperty(document, 'visibilityState', { + configurable: true, + value: 'visible', + }); + document.dispatchEvent(new Event('visibilitychange')); + }); + + expect(result.current).toBe(true); + }); + + it('should return false when document becomes hidden', () => { + const { result } = renderHook(() => useDocumentVisibility()); + + act(() => { + Object.defineProperty(document, 'visibilityState', { + configurable: true, + value: 'visible', + }); + document.dispatchEvent(new Event('visibilitychange')); + }); + expect(result.current).toBe(true); + + act(() => { + Object.defineProperty(document, 'visibilityState', { + configurable: true, + value: 'hidden', + }); + document.dispatchEvent(new Event('visibilitychange')); + }); + 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 event listener on unmount', () => { + const removeEventListenerSpy = jest.spyOn(document, 'removeEventListener'); + + const { unmount } = renderHook(() => useDocumentVisibility()); + unmount(); + + expect(removeEventListenerSpy).toHaveBeenCalledWith('visibilitychange', expect.any(Function)); + + removeEventListenerSpy.mockRestore(); + }); +}); From edcc19a920aeb28bf2d41eeda17208af4dcb147c Mon Sep 17 00:00:00 2001 From: lukKowalski Date: Wed, 21 Oct 2026 09:11:54 +0200 Subject: [PATCH 2/3] docs: add useDocumentVisibility to README Co-Authored-By: Claude Opus 5.5 --- README.md | 1 + 1 file changed, 1 insertion(+) 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) From 51b000b33d98cc461d55a11c6f87288119620ba5 Mon Sep 17 00:00:00 2001 From: lukKowalski Date: Wed, 21 Oct 2026 09:11:54 +0200 Subject: [PATCH 3/3] test(useDocumentVisibility): fix tautological visibility test and verify listener cleanup Co-Authored-By: Claude Opus 5.5 --- tests/useDocumentVisibility.test.ts | 69 +++++++++++++++++++---------- 1 file changed, 45 insertions(+), 24 deletions(-) diff --git a/tests/useDocumentVisibility.test.ts b/tests/useDocumentVisibility.test.ts index 5ddc0ed09d..0531fe0fa7 100644 --- a/tests/useDocumentVisibility.test.ts +++ b/tests/useDocumentVisibility.test.ts @@ -1,14 +1,20 @@ import { renderHook, act } from '@testing-library/react-hooks'; import useDocumentVisibility from '../src/useDocumentVisibility'; -describe('useDocumentVisibility', () => { - const originalVisibilityState = document.visibilityState; +type VisibilityState = 'visible' | 'hidden'; + +const setVisibilityState = (state: VisibilityState) => { + Object.defineProperty(document, 'visibilityState', { + configurable: true, + value: state, + }); + document.dispatchEvent(new Event('visibilitychange')); +}; +describe('useDocumentVisibility', () => { afterEach(() => { - Object.defineProperty(document, 'visibilityState', { - configurable: true, - value: originalVisibilityState, - }); + // Remove the own-property override so the native getter is used again + delete (document as { visibilityState?: VisibilityState }).visibilityState; }); it('should be defined', () => { @@ -34,37 +40,35 @@ describe('useDocumentVisibility', () => { }); it('should return true when document becomes visible', () => { - const { result } = renderHook(() => useDocumentVisibility(true)); + const { result } = renderHook(() => useDocumentVisibility(false)); act(() => { - Object.defineProperty(document, 'visibilityState', { - configurable: true, - value: 'visible', - }); - document.dispatchEvent(new Event('visibilitychange')); + 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(() => { - Object.defineProperty(document, 'visibilityState', { - configurable: true, - value: 'visible', - }); - document.dispatchEvent(new Event('visibilitychange')); + setVisibilityState('visible'); }); expect(result.current).toBe(true); act(() => { - Object.defineProperty(document, 'visibilityState', { - configurable: true, - value: 'hidden', - }); - document.dispatchEvent(new Event('visibilitychange')); + setVisibilityState('hidden'); }); expect(result.current).toBe(false); }); @@ -79,14 +83,31 @@ describe('useDocumentVisibility', () => { addEventListenerSpy.mockRestore(); }); - it('should remove event listener on unmount', () => { + 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', expect.any(Function)); + 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); + }); });