@pol-studios/hooks

React hooks for POL applications

A comprehensive collection of React hooks for state management, storage, device detection, network status, file handling, toasts, forms, and debugging.

Installation

pnpm add @pol-studios/hooks

Peer Dependencies

pnpm add react react-dom @pol-studios/features @pol-studios/utils

Quick Start

import {
  useLocalStorage,
  useOnline,
  useMobile,
  useToast,
} from "@pol-studios/hooks";

function MyComponent() {
  // Persist state to localStorage
  const [theme, setTheme] = useLocalStorage("theme", "light");

  // Check network status
  const isOnline = useOnline();

  // Check device type
  const isMobile = useMobile();

  // Show toast notifications
  const { toast } = useToast();

  return (
    <button onClick={() => toast({ title: "Hello!" })}>
      Show Toast
    </button>
  );
}

Subpath Exports

| Path | Description | |------|-------------| | @pol-studios/hooks | All exports | | @pol-studios/hooks/state | State management hooks (usePartialState, useQueuedState, useDelayedValue) | | @pol-studios/hooks/scroll | Scroll hooks (useScrollPosition, useScrollDirection, useHideOnScroll) | | @pol-studios/hooks/storage | Storage hooks (useLocalStorage, useSessionStorage, useIndexedDB) | | @pol-studios/hooks/device | Device hooks (useDevice, useMobile, useTheme, useDimensions) | | @pol-studios/hooks/network | Network hooks (useOnline, useNetworkStatus, useMutationQueue) | | @pol-studios/hooks/lifecycle | Lifecycle hooks (useMounted, useAfterMount, useOnScreen) | | @pol-studios/hooks/file | File hooks (useFileDialog, useDownload) | | @pol-studios/hooks/toast | Toast hooks (useToast, toast) | | @pol-studios/hooks/form | Form hooks (OnValueChangedContext) | | @pol-studios/hooks/debug | Debug hooks (useRenderCount, useStateTracker) | | @pol-studios/hooks/utils | Utilities (withComponentMemo, isDevEnvironment) |

API Reference

State Hooks

usePartialState

Partial state updates without spreading.

import { usePartialState } from "@pol-studios/hooks/state";

const [state, updateState] = usePartialState({ name: "", email: "" });
updateState({ name: "John" }); // Only updates name, keeps email

useQueuedState

Queue state updates for batching.

import { useQueuedState } from "@pol-studios/hooks/state";

const [state, queueUpdate, flush] = useQueuedState(initialState);

useDelayedValue

Debounce value changes.

import { useDelayedValue, useDelayedState } from "@pol-studios/hooks/state";

const debouncedSearch = useDelayedValue(searchTerm, 300);
const [value, setValue, debouncedValue] = useDelayedState("", 300);

useChangeTracking

Track changes to state values.

import { useChangeTracking, ChangeTrackingProvider } from "@pol-studios/hooks/state";

const { hasChanges, trackChange, resetChanges } = useChangeTracking();

Storage Hooks

useLocalStorage

Persist state to localStorage.

import { useLocalStorage, useLocalStorageState } from "@pol-studios/hooks/storage";

const [value, setValue] = useLocalStorage("key", defaultValue);

useSessionStorage

Persist state to sessionStorage.

import { useSessionStorage } from "@pol-studios/hooks/storage";

const [value, setValue] = useSessionStorage("key", defaultValue);

useIndexedDB

Interact with IndexedDB.

import { useIndexedDB, IndexedDBService } from "@pol-studios/hooks/storage";

const db = useIndexedDB({ dbName: "myDb", storeName: "myStore" });
await db.set("key", value);
const data = await db.get("key");

Device Hooks

useMobile

Detect mobile devices.

import { useMobile, useIsMobile } from "@pol-studios/hooks/device";

const isMobile = useMobile();

useTheme

Detect and manage theme preference.

import { useTheme, useThemeDetector } from "@pol-studios/hooks/device";

const theme = useThemeDetector(); // "light" | "dark"

useDimensions

Track element dimensions.

import { useDimensions, useWindowDimensions } from "@pol-studios/hooks/device";

const [ref, dimensions] = useDimensions();
const { width, height } = useWindowDimensions();

useReducedMotion

Respect user motion preferences.

import { useReducedMotion } from "@pol-studios/hooks/device";

const prefersReducedMotion = useReducedMotion();

Network Hooks

useOnline

Check online status.

import { useOnline, useNetworkStatus } from "@pol-studios/hooks/network";

const isOnline = useOnline();
const { online, effectiveType } = useNetworkStatus();

useMutationQueue

Queue mutations for offline support.

import { useMutationQueue } from "@pol-studios/hooks/network";

const { queue, addMutation, processMutations } = useMutationQueue();

Scroll Hooks

useScrollPosition

Track scroll position.

import { useScrollPosition, useScrollDirection } from "@pol-studios/hooks/scroll";

const scrollY = useScrollPosition();
const direction = useScrollDirection(); // "up" | "down"

useHideOnScroll

Hide elements on scroll down.

import { useHideOnScroll } from "@pol-studios/hooks/scroll";

const isHidden = useHideOnScroll();

Lifecycle Hooks

useMounted

Check if component is mounted.

import { useMounted, useAfterMount } from "@pol-studios/hooks/lifecycle";

const isMounted = useMounted();

useAfterMount(() => {
  // Runs after first render
});

useOnScreen

Detect element visibility.

import { useOnScreen } from "@pol-studios/hooks/lifecycle";

const [ref, isVisible] = useOnScreen({ threshold: 0.5 });

File Hooks

useFileDialog

Open file picker dialog.

import { useFileDialog } from "@pol-studios/hooks/file";

const { openDialog, files } = useFileDialog({ accept: "image/*" });

useDownload

Download files programmatically.

import { useDownload, useDownloadApiFile } from "@pol-studios/hooks/file";

const download = useDownload();
download(blob, "filename.pdf");

Toast Hooks

useToast

Show toast notifications.

import { useToast, toast } from "@pol-studios/hooks/toast";

const { toast: showToast, dismiss } = useToast();

// Imperative API
toast({ title: "Success!", description: "Operation completed." });

// Hook API
showToast({ title: "Hello", variant: "success" });

Form Hooks

OnValueChangedContext

Track form value changes.

import {
  OnValueChangedContextProvider,
  OnValueChangedContext,
} from "@pol-studios/hooks/form";

<OnValueChangedContextProvider onTrigger={handleFieldChange}>
  <MyForm />
</OnValueChangedContextProvider>

Debug Hooks

useRenderCount

Count component renders (dev only).

import { useRenderCount, useStateTracker } from "@pol-studios/hooks/debug";

useRenderCount("MyComponent"); // Logs render count

useStateTracker(state, "myState"); // Logs state changes

Utilities

withComponentMemo

HOC for memoizing components.

import { withComponentMemo } from "@pol-studios/hooks/utils";

const MemoizedComponent = withComponentMemo(MyComponent);

TypeScript Types

import type {
  // Toast types
  ToasterToast,
  Toast,
  ToastState,
  ToastAction,

  // Network types
  NetworkStatus,
  OnlineStatus,
  QueuedMutation,

  // Storage types
  StorageService,
  IndexDbService,
  DBOptions,

  // Form types
  ValueChangeTrigger,
  OnValueChangedContextValue,
} from "@pol-studios/hooks";

Related Packages

• @pol-studios/utils - Utility functions
• @pol-studios/features - Feature modules
• @pol-studios/ui - UI components

License

UNLICENSED