🧠 useBrowserAPI

A powerful React hook based on useSyncExternalStore that lets you subscribe to modern browser APIs like:

• 📡 network status
• 📝 text selection
• 🧭 scroll position
• 🖥 fullscreen mode
• 📱 device orientation
• 👁️ page visibility
• and many more...

Built for React 18+ with full TypeScript support and intuitive usage.

📦 Installation

npm install use-browser-api

import { useBrowserAPI } from "use-browser-api";

🚀 Usage Example

const { online } = useBrowserAPI("network");
const { width, height } = useBrowserAPI("viewport");
const { text } = useBrowserAPI("selection");
const { x, y } = useBrowserAPI("scrollPosition", { ref: myRef });

All values returned are reactive and update when the related event fires.

🔧 Supported Browser APIs

| API Name | Hook Call Example | Options (2nd param) | |-----------------------|------------------------------------------------------------------|----------------------------------------------------------------------------------------| | network | useBrowserAPI("network") | — | | pageVisibility | useBrowserAPI("pageVisibility") | — | | deviceOrientation | useBrowserAPI("deviceOrientation", { deviceOrientationPermission }) | { deviceOrientationPermission: boolean } (required on iOS/Android) | | viewport | useBrowserAPI("viewport") | — | | pageFocus | useBrowserAPI("pageFocus") | — | | scrollPosition | useBrowserAPI("scrollPosition", { ref }) | { ref: RefObject<HTMLElement> } | | beforeUnload | useBrowserAPI("beforeUnload") | — | | fullscreen | useBrowserAPI("fullscreen") | — | | selection | useBrowserAPI("selection") | — | | screenOrientation | useBrowserAPI("screenOrientation") | — | | intersection | useBrowserAPI("intersection", { ref }) | { ref: RefObject<HTMLElement> } | | storage | useBrowserAPI("storage", { storageKey }) | { storageKey: string } | | clipboardEvents | useBrowserAPI("clipboardEvents") | — |

📙 API Output Examples

| API | Returned Properties | |--------------------|----------------------------------------------| | network | { online: boolean } | | selection | { text: string \| null } | | scrollPosition | { x: number, y: number } | | deviceOrientation| { alpha, beta, gamma } | | fullscreen | { active: boolean } | | intersection | { isIntersecting: boolean, ratio: number }| | clipboardEvents | { action: "copy" \| "cut" \| "paste", data: string } | | etc. | Varies depending on the API selected |

🧪 Full Demo

Check out the full example in demo-browser-api.tsx or preview usage:

const { visible } = useBrowserAPI("pageVisibility");

useEffect(() => {
  if (!visible) {
    console.log("User left the page");
  }
}, [visible]);

🛠 Contributing

Pull requests welcome! If you'd like to add new browser APIs, feel free to open an issue or fork the repo.

📄 License

MIT © ChristBM

Made with ❤️ for React developers who love the browser.