Solution

You will keep one React state value synchronized with the browser's current page-visibility signal.

The problem, in plain English

A video player can stop rendering frames when its tab is hidden. An analytics dashboard can postpone refreshes until the user returns. Both need the document's real visibility state, not a guess based on whether the window has focus. Your hook reads that state, listens for the browser's visibility event, and removes the listener when its component leaves the page.

The mental model

Treat document.visibilityState as the source of truth and React state as a copy that drives rendering. The browser changes the source first, then dispatches visibilitychange; the event is your signal to read the source again.

A first attempt

const { useState } = require('react');

function usePageVisibility(defaultValue = 'visible') {
  const [visibility] = useState(() => {
    if (typeof document === 'undefined') return defaultValue;
    return document.visibilityState || defaultValue;
  });
  return visibility;
}

This version is safe and returns the right initial value. But a state initializer runs only during the first render. When the browser later changes from 'visible' to 'hidden', nothing tells React to read the document again, so the returned value stays stale.

The working solution

const { useEffect, useRef, useState } = require('react');

function readVisibility(fallback) {
  if (typeof document === 'undefined') return fallback;
  const value = document.visibilityState;
  return value === 'visible' || value === 'hidden' ? value : fallback;
}

function usePageVisibility(defaultValue = 'visible') {
  const defaultRef = useRef(defaultValue);
  defaultRef.current = defaultValue;

  const [visibility, setVisibility] = useState(() =>
    readVisibility(defaultValue)
  );

  useEffect(() => {
    if (typeof document === 'undefined') return undefined;

    // Read inside the handler because the document can change after mount.
    const handleVisibilityChange = () => {
      setVisibility(readVisibility(defaultRef.current));
    };

    document.addEventListener('visibilitychange', handleVisibilityChange);
    // The document wins if it changed between render and effect setup.
    handleVisibilityChange();

    return () => {
      document.removeEventListener('visibilitychange', handleVisibilityChange);
    };
  }, []);

  return visibility;
}

module.exports = { usePageVisibility };

readVisibility narrows every result to the hook's two allowed strings and falls back safely when no document signal exists. The effect creates one handler, adds that exact function to the document, and returns a cleanup that removes it. defaultRef keeps a later fallback value available to the stable handler without resubscribing on every render.

Walking through one call

Start with a visible tab and call usePageVisibility('hidden').

1. First render. readVisibility('hidden') sees document.visibilityState === 'visible', so the hook returns 'visible'. The real document value wins over the fallback.
2. Effect setup. React adds one visibilitychange handler to document. It immediately runs the handler once, closing the small render-to-effect timing gap.
3. The tab becomes hidden. The browser sets document.visibilityState to 'hidden' and dispatches visibilitychange.
4. Fresh read. The handler reads 'hidden' at that moment and calls setVisibility('hidden'). React rerenders the component with the new result.
5. Unmount. The cleanup passes the same handler reference to removeEventListener, so later visibility changes cannot update this hook instance.

Gotchas

• Reading only during mount. The first result is correct, but it never changes when the tab becomes hidden. Fix: subscribe to visibilitychange and read again inside its handler.
• Listening on window. The Page Visibility API dispatches visibilitychange on document; a window blur can also happen while the page remains visible. Fix: use the document event and its state.
• Capturing the first fallback forever. A stable handler closes over values from the render that created it. Fix: keep the latest fallback in a ref so rerenders do not require a new subscription.
• Removing a different function. removeEventListener('visibilitychange', () => update()) cannot remove the function originally added. Fix: define one handler and pass the same reference to both calls.
• Assuming the API always exists. Server rendering has no document, and some environments omit visibilityState. Fix: guard the read and return the caller's fallback.

Going further

• Pause a resource. Combine the hook with a media player, animation loop, or polling hook so hidden work stops and visible work resumes.
• Use useSyncExternalStore. Model document visibility as an external browser store when you need a server snapshot and React's subscription contract in a shared utility.
• Track richer lifecycle signals. Add pagehide, pageshow, or the Page Lifecycle API when freezing and back-forward cache restoration matter; those events answer different questions from visibility alone.