@alkeshgupta/tab-visibility

A lightweight utility that lets you detect when the browser tab becomes visible or hidden, trigger custom callbacks, and optionally auto-pause media (video/audio) when the user switches tabs.

Perfect for analytics, UX improvements, pausing timers, audio/video control, and more — with APIs for both React and Vanilla JS.

✨ Features

• Detect when the tab is shown
• Detect when the tab is hidden
• Register multiple callbacks
• Works in React (custom hook style) and Vanilla JS
• Auto pause video/audio when tab is hidden
• Easy setup — tiny API
• Lightweight & dependency-free

📦 Installation

npm install @alkeshgupta/tab-visibility

or

yarn add @alkeshgupta/tab-visibility

🧠 Basic Usage

import { useTabVisibility } from "@alkeshgupta/tab-visibility";

useTabVisibility.onShow(() => {
  console.log("Tab is visible again!");
});

useTabVisibility.onHide(() => {
  console.log("User switched tab!");
});

⚛️ React Usage Example

Works anywhere inside your components.

import { useEffect } from "react";
import { useTabVisibilityHook } from "@alkeshgupta/tab-visibility";

function MyComponent() {
  useTabVisibilityHook({
    onHide: () => {
      console.log("User switched tab!");
    },

    onShow: () => {
      console.log("Tab is visible again!");
    },
  });

  return <div>Watching tab visibility</div>;
}

export default MyComponent;

You can register as many event handlers as you want.

🔊 Auto Pause Media (Video/Audio)

Automatically pause all and elements when the tab becomes hidden:

import { autoPauseMedia } from "@alkeshgupta/tab-visibility";

useEffect(() => {
  autoPauseMedia();
}, []);

Optional - Ignore Muted Media:

import { autoPauseMedia } from "@alkeshgupta/tab-visibility";

useEffect(() => {
  autoPauseMedia({ ignoreMuted: true });
}, []);

🧩 Vanilla Example (HTML)

Works anywhere inside your components.

<script type="module">
  import { useTabVisibility } from "https://cdn.jsdelivr.net/npm/@alkeshgupta/[email protected]/src/index.js";

  useTabVisibility.onShow(() => {
    console.log("Tab is visible again!");
  });

  useTabVisibility.onHide(() => {
    console.log("User switched tab!");
  });
</script>

🧬 API Reference

onShow(callback: Function)

Registers a function to run when tab becomes visible.

onShow(() => console.log("Welcome back!"));

onHide(callback: Function)

Registers a function to run when tab becomes hidden.

onHide(() => console.log("Hey come back 👀"));

autoPauseMedia()

Pauses all video and audio elements on the page.

autoPauseMedia();

autoPauseMedia({ ignoreMuted: true })

Pauses all unmuted video and audio elements on the page.

autoPauseMedia({ ignoreMuted: true });

📜 Browser Support

✅ Chrome
✅ Firefox
✅ Edge
✅ Safari
✅ Opera

Uses the standard visibilitychange API, widely supported.

📏 Notes

• All callbacks can be registered multiple times.
• Order of callbacks is preserved.
• Works in frameworks (React, Next.js, etc.) after mount.

📄 License

MIT License © 2025 Alkesh Gupta
Feel free to use, modify, and distribute.

⭐ Support

If you like this library, consider:

• leaving a GitHub & npm star ⭐
• reporting issues
• contributing ideas