Visibility.js

2.0.2 · active · verified Tue Apr 21

Visibility.js is a lightweight JavaScript library providing a robust wrapper around the native Page Visibility API, abstracting away vendor prefixes and offering enhanced utility functions. The current stable version is 2.0.2, with recent updates focusing on modernizing its distribution (removing support for legacy package managers in 2.0.0) and improving TypeScript definitions. Its core strength lies in intelligent timers and event handlers: `Visibility.every` creates timers that automatically pause or adjust intervals when a page is hidden, optimizing resource usage, while `onVisible` and `onHidden` provide direct callbacks for state changes. A key differentiator is its built-in fallback for older browsers, although this feature has a known limitation when a browser window loses focus but remains visible.

Common errors

```
Visibility is not defined
```
cause The `Visibility` object was not correctly imported or the script was not loaded/executed in the global scope.

fix Ensure you are using `import Visibility from 'visibilityjs';` at the top of your module file, or that the library's script is properly included in your HTML before its usage.
```
TypeError: clearInterval is not a function at Object.Visibility.every
```
cause Attempting to use `clearInterval()` with the ID returned by `Visibility.every()`, which is not a standard `setInterval` ID.

fix Use `Visibility.stop(timerId)` to clear timers created by `Visibility.every()`. For example: `const timer = Visibility.every(...); Visibility.stop(timer);`
```
TS2307: Cannot find module 'visibilityjs' or its corresponding type declarations.
```
cause TypeScript compiler cannot locate the type definitions for the `visibilityjs` package.

fix Ensure `visibilityjs` is installed correctly via npm/yarn (`npm install visibilityjs` or `yarn add visibilityjs`). If issues persist, check your `tsconfig.json` for `moduleResolution` settings.

Warnings

breaking Version 2.0.0 removed official support for legacy package managers and module loaders including Bower, Sprockets, and Component. Projects still relying on these will need to update their dependency management.
Fix: Migrate to npm/yarn and use modern JavaScript module imports (ESM). Consider transpilation for older browser environments if not already in place.
gotcha The fallback mechanism (`lib/visibility.fallback.js`) for browsers without native Page Visibility API support has a known limitation: if the browser window loses focus but remains visually open (e.g., another application covers it partially), its state may incorrectly report as 'hidden'.
Fix: Be aware of this edge case when relying on the fallback behavior. This primarily affects very old browsers; modern browsers typically support the native API.
gotcha Timers created with `Visibility.every()` cannot be stopped using the standard `clearInterval()` function. A custom `Visibility.stop()` method must be used instead.
Fix: Always use `Visibility.stop(timerId)` to clear timers created by `Visibility.every(interval, callback)`.

Install

npm install visibilityjs npm
yarn add visibilityjs yarn
pnpm add visibilityjs pnpm

Imports

Visibility
wrong:
```
const Visibility = require('visibilityjs');
```
correct:
```
import Visibility from 'visibilityjs';
```
The library primarily exports a default `Visibility` object with all its methods. CommonJS `require` is not officially supported since v2.0.0.
Visibility.every
wrong:
```
import { every } from 'visibilityjs';
```
correct:
```
import Visibility from 'visibilityjs';
Visibility.every(1000, () => { /* ... */ });
```
Methods like `every` are properties of the main `Visibility` object, not direct named exports.
Visibility.onVisible
wrong:
```
import { onVisible } from 'visibilityjs';
```
correct:
```
import Visibility from 'visibilityjs';
Visibility.onVisible(() => { /* ... */ });
```
Methods like `onVisible` are properties of the main `Visibility` object, not direct named exports.

Quickstart

Demonstrates how to use `Visibility.every` for interval-based tasks, `Visibility.stop` to clear timers, and `Visibility.onVisible`/`onHidden` for reacting to page visibility state changes.

import Visibility from 'visibilityjs';

// Example 1: Update a countdown every second only when the page is visible
const countdownTimerId = Visibility.every(1000, () => {
  console.log('Page is visible! Updating countdown...');
  // In a real app, you would update a UI element here
});

// Example 2: Check for emails every minute when visible, every 5 minutes when hidden
const emailCheckTimerId = Visibility.every(60 * 1000, 5 * 60 * 1000, () => {
  console.log('Checking for new emails...');
  // Make an AJAX request or similar
});

// Stop a timer after 10 seconds for demonstration
setTimeout(() => {
  Visibility.stop(countdownTimerId);
  console.log('Countdown timer stopped.');
}, 10000);

// Example 3: Perform an action when the page becomes visible
Visibility.onVisible(() => {
  console.log('Welcome back! Page is now visible.');
  // Resume video playback or animations
});

// Example 4: Perform an action when the page becomes hidden
Visibility.onHidden(() => {
  console.log('Page is now hidden. Pausing heavy tasks.');
  // Pause video, stop heavy animations, etc.
});

view raw JSON →