use-web-kit

use-web-kit

A compact collection of zero-runtime-dependency, TypeScript-first React hooks for common browser interactions.

Installation

npm install use-web-kit

Quick Example

import { useStorage, usePermission, useMediaControls } from "use-web-kit";

function App() {
  const [theme, setTheme] = useStorage("theme", "light");
  const { state: camState } = usePermission("camera");
  const { ref, state, controls } = useMediaControls();

  return (
    <>
      <button
        onClick={() => setTheme((t) => (t === "light" ? "dark" : "light"))}
      >
        Theme: {theme}
      </button>
      <p>Camera permission: {camState}</p>
      <video ref={ref} src="/clip.mp4" />
      <button onClick={state.paused ? controls.play : controls.pause}>
        {state.paused ? "Play" : "Pause"}
      </button>
    </>
  );
}

Hooks

Utility

Hook	Description	Docs
useIdleQueue	Schedule non-critical tasks during browser idle time	API →
useBroadcastState	Sync state across browser tabs via BroadcastChannel	API →
useAdaptivePolling	Run a callback at an interval; slows/pauses when backgrounded	API →
useNetworkStatus	Reactive navigator.onLine + Network Information API	API →
useIntersection	Pooled IntersectionObserver with a ref-callback interface	API →
usePageLifecycle	Track page visibility, focus, and freeze state	API →

Browser API

Hook	Description	Docs
useStorage	localStorage / sessionStorage with cross-tab sync	API →
usePermission	Query and watch Web Permissions API state	API →
useMediaControls	Attach to <audio>/<video> with reactive state + controls	API →

Full API reference:

• Utility Hooks
• Browser API Hooks

Features

• Zero runtime dependencies
• Tree-shakeable named exports — import only what you use
• Strict TypeScript typings included
• SSR-safe — all hooks guard window / navigator access
• Graceful fallbacks for unsupported browser APIs

SSR Compatibility

Every hook tests for window, navigator, and the relevant API before accessing it. In a server render:

• useStorage returns initialValue
• usePermission returns { state: "unavailable", loading: false }
• useNetworkStatus returns { online: true }
• useIntersection returns { isIntersecting: false, entry: undefined }
• usePageLifecycle returns { visible: false, focused: false, frozen: false }
• useMediaControls returns default state with a no-op ref

Bundle / Tree-shaking

All hooks are named exports at the package root:

import { useIdleQueue } from "use-web-kit"; // only useIdleQueue bundled
import { useStorage, usePermission } from "use-web-kit"; // two hooks bundled

The package ships both ESM (dist/index.mjs) and CJS (dist/index.js) builds via tsup.

Testing

npm test            # run all tests once
npm test -- --watch # watch mode

All hooks are thoroughly tested with Jest and @testing-library/react.

Contributing

• Fork the repo and create a feature branch.
• npm install to set up dependencies.
• Write tests alongside your changes.
• Ensure npm test passes with no failures.
• Open a pull request with a clear description.

License

MIT