document-visibility

Observe document visibility without touching browser globals during module evaluation.


Package	`@vizejs/composable/document-visibility`
Own the source	`vize lib pull composable:document-visibility`
Runtime exports	`useDocumentVisibility`
Gzip budget	1536 B

Usage

import { useDocumentVisibility } from "@vizejs/composable/document-visibility";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useDocumentVisibility`	events	experimental	deterministic-fallback	caller-managed	reactive-scope	web, desktop	`document`	—

API

`useDocumentVisibility`

Observe document visibility without touching browser globals during module evaluation. The composable is safe during server rendering: when no host resolves, it exposes ssrState and marks supported false. During hydration or tests, passing a host attaches exactly one visibilitychange listener and removes it when the reactive host changes or the owning scope stops. Unsupported or future visibility states normalize to "hidden" so consumers fail closed instead of accidentally treating a prerendered or unloaded page as visible.

function useDocumentVisibility( options: UseDocumentVisibilityOptions = {}, ): DocumentVisibilityControls

Types

`DocumentVisibilityHost`

Capability required to observe document visibility.

Member	Type	Description
`visibilityState`?	`string`	Current browser visibility state. Unknown states are treated as hidden.
`hidden`?	`boolean`	Legacy visibility flag used when `visibilityState` is absent.
`addEventListener`	`( event: "visibilitychange", listener: EventListener, options?: boolean \| AddEventListenerOptions, ) => void`	Subscribe to `visibilitychange`.
`removeEventListener`	`( event: "visibilitychange", listener: EventListener, options?: boolean \| EventListenerOptions, ) => void`	Remove a previous `visibilitychange` listener.

`UseDocumentVisibilityOptions`

Options for useDocumentVisibility.

Member	Type	Description
`ssrState`?	`PageVisibilityState`	State exposed while no document capability is available.
`host`?	`MaybeRefOrGetter<DocumentVisibilityHost \| null \| undefined>`	Reactive document capability for alternate runtimes and tests.
`flush`?	`"pre" \| "post" \| "sync"`	Reactive subscription update timing.

`DocumentVisibilityControls`

Reactive state returned by useDocumentVisibility.

Member	Type	Description
`state`	`Readonly<Ref<PageVisibilityState>>`	Current visibility state, using the configured SSR fallback while unsupported.
`supported`	`Readonly<Ref<boolean>>`	Whether a concrete document capability is currently attached.
`visible`	`ComputedRef<boolean>`	Whether `state` is `"visible"`.
`hidden`	`ComputedRef<boolean>`	Whether `state` is `"hidden"`.