# useDocumentVisibility

The page's `document.visibilityState` (`'visible'` or `'hidden'`), updated when the user switches tabs, minimizes the window, or locks the screen.

Renders `serverValue` on the server and during hydration, then switches to the real state with no hydration mismatch.

## Import

```ts
import { useDocumentVisibility } from '@vincent.ri/react-tils'
// or only this hook
import { useDocumentVisibility } from '@vincent.ri/react-tils/useDocumentVisibility'
```

## Usage

```ts
const visibility = useDocumentVisibility()
useEffect(() => {
  if (visibility === 'hidden') return
  const id = setInterval(refresh, 5000)
  return () => clearInterval(id)
}, [visibility])
```

## When to use it

Pausing polling, video, animations, or timers while the page is hidden, or refreshing data when the user comes back.

## When not to

You need to know if an element is on screen; use `useInView`. Don't use it to save state before the page closes; listen for `pagehide` instead, since a hidden page may never become visible.

## API

```ts
function useDocumentVisibility(serverValue?: DocumentVisibilityState): DocumentVisibilityState
```

| Parameter | Description |
| --- | --- |
| `serverValue` | State on the server and during hydration. Default `'visible'`. |

## Browser support

Works in all modern browsers.

## Coming from another library?

Other libraries call this `usePageVisibility`.

---

101 B minified and brotlied
Source: https://github.com/vincentri/react-tils/blob/main/src/useDocumentVisibility.ts
Docs page: https://vincentri.github.io/react-tils/hooks/useDocumentVisibility/
Previous: [useNetworkInformation](https://vincentri.github.io/react-tils/hooks/useNetworkInformation.md)
Next: [useWindowFocus](https://vincentri.github.io/react-tils/hooks/useWindowFocus.md)