visibility-listener
Track document visibility state seamlessly across browsers.
Installation
You can install the package using npm/yarn/pnpm:
npm install visibility-listener
# or
yarn add visibility-listener
# or
pnpm add visibility-listener
Examples
import createVisibilityStateListener from 'visibility-listener';
const listener = createVisibilityStateListener();
listener.on('update', (state) => {
console.log('🔄️ current state =>', state);
if (state === 'visible') {
// do something
} else if (state === 'hidden') {
// do another thing
}
const lastChangeTime = listener.getLastStateChangeTime();
console.log('🕒 last change time =>', new Date(lastChangeTime));
});
listener.start();
API
createVisibilityStateListener(opts?: VisibilityStateListenerOptions): VisibilityStateListener
Creates a visibility state listener instance.
-
opts
(optional): Options object to customize the listener. Available options:-
window
: Custom window object to use for the listener. -
document
: Custom document object to use for the listener. -
eventNames
: Custom event names to use. Supported key:-
update
: Custom name for the update event.
-
-
Returns a VisibilityStateListener
object with the following methods:
on(eventName: string, handler: Function): void
Adds an event listener for the specified event.
-
eventName
(required): The name of the event to listen for. -
handler
(required): The event handler function.
start(): boolean
Starts the visibility state listener.
Returns true
if the listener started successfully, or false
if there was an error during initialization.
pause(): boolean
Pauses the visibility state listener, preventing the emission of events.
Returns true
if the listener was paused successfully, or false
if there was an error.
hasError(): boolean
Checks if there is an error with the listener.
Returns true
if there is an error, or false
if there is no error.
getError(): string | null
Gets the error message associated with the listener, if any.
Returns the error message as a string, or null
if there is no error.
getState(): string
Gets the current visibility state.
Returns the current visibility state as a string.
getLastStateChangeTime(): number
Gets the timestamp of the last state change in milliseconds.
Returns the timestamp of the last state change as a number.
getStateChangeCount(): number
Gets the total number of state changes since the listener started.
Returns the total number of state changes as a number.
License
This package is released under the MIT License.