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); + }); +});