onDocumentVisible

onDocumentVisible(fn) calls fn once with the current visibility boolean, then again whenever the document is shown or hidden — use it for pausing timers, stopping animations, or refreshing data when the tab regains focus. For a reactive accessor use useDocumentVisible. Part of pota/use/visibility.

It must be called within a reactive scope (a component body, an effect, a root, etc.). Internally it subscribes to visibilitychange inside an effect and registers its teardown with the surrounding owner; when that scope disposes, the subscription is removed. Called with no owner there is nothing to clean up the listener and it leaks.

Arguments

Argument	Type	Description
fn	(visible: boolean) => void	Called once on subscription, then on each change.

Returns: undefined.

Examples

Logging visibility changes

Appends a timestamped entry to the log each time the tab is shown or hidden — the first entry appears immediately, from the initial call with the current value. Because the subscription is owned by the component, it is removed automatically when the component unmounts.

import { render, signal } from 'pota'
import { onDocumentVisible } from 'pota/use/visibility'

function App() {
	const log = signal([])

	onDocumentVisible(visible => {
		log.update(entries => [
			...entries,
			`${new Date().toLocaleTimeString()} — ${
				visible ? 'visible' : 'hidden'
			}`,
		])
	})

	return (
		<div>
			<p>Switch tabs to populate the log:</p>
			<ul>
				{() =>
					log.read().map(entry => (
						<li>
							<code>{entry}</code>
						</li>
					))
				}
			</ul>
		</div>
	)
}

render(App)