Elements

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

Document Visibility

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

Instant

visible

2s delay

visible

import { 
const useDocumentVisibility: () => Observable<DocumentVisibilityState>
useDocumentVisibility } from "@usels/web";

function 
function Component(): JSX.Element
Component() {
  const 
const visibility$: any
visibility$ = 
function useDocumentVisibility(): Observable<DocumentVisibilityState>
Framework-agnostic reactive document visibility state.
Tracks the browser tab's visibility state ('visible' or 'hidden').
Returns a writable Observable<DocumentVisibilityState> that updates
automatically when the user switches tabs or minimizes the window.
SSR-safe: returns 'visible' when document is not available.
@returns ― Observable<DocumentVisibilityState> — reflects current tab visibility.
useDocumentVisibility();

  return <
JSX.IntrinsicElements.p: DetailedHTMLProps<HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>
p>Tab is {
const visibility$: any
visibility$.
any
get()}</
JSX.IntrinsicElements.p: DetailedHTMLProps<HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>
p>;
}

import { createDocumentVisibility } from "@usels/web";

function Component() {
  "use scope"
  const visibility$ = createDocumentVisibility();

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

Pausing work when the tab is hidden

Hook
Scope

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

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

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

import { createDocumentVisibility } from "@usels/web";
import { observe } from "@usels/core";

function Component() {
  "use scope"
  const visibility$ = createDocumentVisibility();

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

Tracking page view time

Hook
Scope

import { useDocumentVisibility } from "@usels/web";
import { useObservable, useObserve } from "@usels/core";

function Component() {
  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);
    }
  });
}

import { createDocumentVisibility } from "@usels/web";
import { observe } from "@usels/core";
import { observable } from "@usels/core";

function Component() {
  "use scope"
  const visibility$ = createDocumentVisibility();
  const visibleSince = observable(Date.now());

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

Type

Returns

ObservablePrimitive<DocumentVisibilityState>

Name	Type	Description
`peek`	`{ (): DocumentVisibilityState; (): DocumentVisibilityState; }`	-
`get`	`(trackingType?: TrackingType \| GetOptions) => DocumentVisibilityState`	-
`onChange`	`(cb: ListenerFn<DocumentVisibilityState>, options?: { trackingType?: TrackingType; initial?: boolean \| undefined; immediate?: boolean \| undefined; noArgs?: boolean \| undefined; } \| undefined) => () => void`	-
`set`	`{ (value: (prev: DocumentVisibilityState) => DocumentVisibilityState): void; (value: ObservablePrimitive<DocumentVisibilityState>): void; (value: "hidden" \| ... 6 more ... \| (() => "visible" \| ... 1 more ... \| ImmutableObservableBase<...>)): void; (value: Promise<...>): void; (value: DocumentVisibilityState): void; }`	-
`delete`	`() => void`	-

Source

View on GitHub