useDocumentVisibility

Tracks the browser tab’s visibility state ('visible' or 'hidden') as a reactive Observable<DocumentVisibilityState>. Updates automatically when the user switches tabs or minimizes the window. SSR-safe: returns 'visible' when document is not available.

Demo

Instant"visible"

2s delay"visible"

Switch to another tab and come back — the 2s delay row stays "hidden" long enough to confirm the transition.

Usage

import { useDocumentVisibility } from "@usels/core";

function Component() {
  const visibility$ = useDocumentVisibility();

  return <p>Tab is {visibility$.get()}</p>;
}

Pausing work when the tab is hidden

const visibility$ = useDocumentVisibility();

useObserve(() => {
  if (visibility$.get() === "hidden") pausePolling();
  else resumePolling();
});

Tracking page view time

const visibility$ = useDocumentVisibility();
const visibleSince = useObservable(Date.now());

useObserve(() => {
  if (visibility$.get() === "visible") {
    visibleSince.set(Date.now());
  } else {
    const elapsed = Date.now() - visibleSince.get();
    trackVisibleTime(elapsed);
  }
});

Type Declarations

export declare function useDocumentVisibility(): Observable<DocumentVisibilityState>;

Source

View on GitHub

Contributors

• tigerwest

Changelog

• a7392ab 2026-03-06 - feat(core,browser): add sync strategy hooks (tigerwest)