useDocumentVisibility

A React hook that tracks the document's current visibility state (visible or hidden).

Overview

useDocumentVisibility listens to the visibilitychange event on the document, allowing your components to react when a user switches tabs or minimizes the window. This is perfect for pausing animations, stopping real-time data fetching, or creating playful "welcome back" interactions.

Demo

Tab Visibility Sensor

The Shy Forest Spirit

Try switching tabs and coming back. Our friend only appears when you're looking!

🌲

🐵

Missed you! ✨

🌳

☁️

Current State

VISIBLE

Times Hidden

Open a new tab, wait 2 seconds, then return!

API Reference

function useDocumentVisibility(): VisibilityState

Returns

Name	Type	Description
`visibility`	`VisibilityState`	Either `'visible'` or `'hidden'`.

Usage Examples

Pause/Resume Timer

import { useDocumentVisibility } from 'react-hooks-ts'
 
function GameTimer() {
  const visibility = useDocumentVisibility()
  const [time, setTime] = useState(0)
 
  useEffect(() => {
    if (visibility === 'visible') {
      const id = setInterval(() => setTime(t => t + 1), 1000)
      return () => clearInterval(id)
    }
  }, [visibility])
 
  return <div>Time: {time}s</div>
}

Welcome Back Message

import { useDocumentVisibility } from 'react-hooks-ts'
 
function AppNotifier() {
  const visibility = useDocumentVisibility()
 
  useEffect(() => {
    if (visibility === 'visible') {
      toast("Great to see you again! ✨")
    }
  }, [visibility])
 
  return null
}

Features

👁️ Instant Sync - Updates state immediately on visibility change.
📉 Optimization - Perfect for reducing CPU/data usage when the tab is inactive.
🛡️ SSR Safe - Returns 'visible' as a default for server-side rendering.
🧹 Automatic Cleanup - Removes event listeners when the component unmounts.