@supunlakmal/hooks

npm

A comprehensive collection of production-ready, reusable React hooks written in TypeScript to simplify common UI patterns and browser API interactions.

Stop reinventing the wheel! @supunlakmal/hooks provides a wide arrays, easy-to-use hooks covering everything from state management enhancements and side effects to browser APIs and performance optimizations.

Why choose @supunlakmal/hooks?

🚀 Extensive Collection: Over 60+ hooks covering a vast range of common React development needs.
🛡️ Type-Safe: Written entirely in TypeScript for robust development.
✨ Simple API: Designed for ease of use and minimal boilerplate.
🌍 SSR Compatible: Hooks are designed to work safely in server-side rendering environments.
🧹 Automatic Cleanup: Handles listeners, timers, and observers correctly.
⚡ Performance Focused: Includes hooks like useDebounce, useThrottle, and useVirtualList for optimization.
🧩 Minimal Dependencies: Core hooks have zero runtime dependencies (unless specified in individual hook docs).

Installation

npm install @supunlakmal/hooks
# or
yarn add @supunlakmal/hooks

Quick Start Example

import React, { useState } from 'react';
import { useToggle, useDebounce, useWindowSize } from '@supunlakmal/hooks';

function ExampleComponent() {
  // Effortlessly manage boolean state
  const [isOpen, toggle] = useToggle(false);

  // Debounce rapid input changes
  const [inputValue, setInputValue] = useState('');
  const debouncedSearchTerm = useDebounce(inputValue, 500);

  // Get window dimensions easily
  const { width, height } = useWindowSize();

  // Use debounced value for API calls, etc.
  React.useEffect(() => {
    if (debouncedSearchTerm) {
      console.log(`Searching for: ${debouncedSearchTerm}`);
      // Fetch API call here...
    }
  }, [debouncedSearchTerm]);

  return (
    <div>
      {/* useToggle Example */}
      <button onClick={toggle}>{isOpen ? 'Close' : 'Open'}</button>
      {isOpen && <p>Content is visible!</p>}

      <hr />

      {/* useDebounce Example */}
      <input
        type="text"
        placeholder="Search..."
        value={inputValue}
        onChange={(e) => setInputValue(e.target.value)}
      />
      <p>Typing: {inputValue}</p>
      <p>Debounced: {debouncedSearchTerm}</p>

      <hr />

      {/* useWindowSize Example */}
      <p>
        Window Size: {width}px x {height}px
      </p>
    </div>
  );
}

Available Hooks

Hooks are organized into thematic categories so you can quickly jump to the patterns you need. Every entry links to its detailed guide in docs/.

1. State Management

Enhanced useState-style primitives for toggles, lists, finite state machines, and other complex data structures.

Hook	Description
`useBoolean`	Manages a boolean state with explicit `setTrue`, `setFalse`, and `toggle` functions.
`useConst`	Initializes and returns a constant value that persists across renders.
`useControlledRerenderState`	A `useState` alternative where the state setter can cancel a re-render.
`useCounter`	Manages a number state with `increment`, `decrement`, `set`, and `reset` actions.
`useCycle`	Cycles through a predefined list of values.
`useDefault`	Returns a default value if the provided value is `null` or `undefined`.
`useDerivedState`	A semantic wrapper around `useMemo` for creating state based on other values.
`useEnum`	Manages state that is constrained to the values of a given enum object.
`useFiniteStateMachine`	Manages complex state using an explicit finite state machine definition.
`useFirstMountState`	Returns `true` only on the first render of a component.
`useFunctionalState`	A `useState` variant that returns a getter function for the state.
`useHistoryState`	Manages state with a history, allowing for undo and redo operations.
`useIsFirstRender`	Returns `true` only on the initial render of a component.
`useIsMounted`	Returns a function that indicates if the component is currently mounted.
`useList`	Manages an array state with a comprehensive set of list manipulation actions.
`useListState`	Manages an array state with basic list manipulation functions.
`useMap`	Manages a `Map` object as state with actions to manipulate it.
`useMapState`	Manages a key-value object as state with `set`, `remove`, and `reset` functions.
`useMediatedState`	A `useState` variant where every value set is passed through a mediator function.
`usePrevious`	Returns the value of a prop or state from the previous render.
`usePreviousDifferent`	Returns the last value that was different from the current value.
`useQueue`	Manages a queue (First-In, First-Out) with methods to `add`, `remove`, and `peek`.
`useResetState`	A `useState` variant that includes a function to reset the state to its initial value.
`useSet`	Manages a `Set` object as state with actions to manipulate it.
`useSetState`	Manages an object state, merging updates similarly to `this.setState` in class components.
`useStateWithHistory`	Manages state with a history of changes, allowing for undo and redo operations.
`useStepper`	Manages state for multi-step forms or wizards.
`useToggle`	Manages a boolean state with a toggle function.

2. Side Effects & Lifecycle

Hooks that orchestrate effects, logging, and lifecycle nuances beyond vanilla useEffect.

Hook	Description
`useConditionalEffect`	A `useEffect` that only runs its callback if a set of conditions are met.
`useCustomCompareEffect`	A `useEffect` that uses a custom comparator function for its dependency array.
`useDeepCompareEffect`	A `useEffect` that performs a deep comparison of its dependencies.
`useDebouncedEffect`	A `useEffect` whose callback function is debounced.
`useIsomorphicLayoutEffect`	A hook that uses `useLayoutEffect` in the browser and `useEffect` on the server.
`useLifecycleLogger`	Logs component lifecycle events (mount, update, unmount) to the console.
`useLogger`	Logs component lifecycle events and prop changes.
`useMount`	Runs a callback function once when the component mounts.
`useThrottledEffect`	A `useEffect` whose callback function is throttled.
`useUnmount`	Runs a callback function when the component unmounts.
`useUnmountEffect`	Runs an effect only when the component is unmounted.
`useUpdateEffect`	A `useEffect` that skips the initial render and only runs on updates.
`useWhyDidYouUpdate`	A debugging tool that logs which props changed on a component re-render.
`useErrorBoundary`	Imperative helpers for programmatically triggering and resetting React error boundaries.
`useReducerLogger`	Wraps `useReducer` to log every action and resulting state, aiding debugging.

3. Data Fetching

Helpers for REST-style data loading, request cancellation, debouncing, and network-aware flows.

Hook	Description
`useAsync`	Manages the state of an asynchronous function call.
`useAsyncAbortable`	An `useAsync` variant that provides an `AbortSignal` to the async function.
`useCachedFetch`	A `useFetch` variant with in-memory caching to avoid redundant requests.
`useDebouncedFetch`	A `useFetch` variant that debounces the request trigger.
`useDelete`	A specialized `useFetch` for making DELETE requests.
`useFetch`	A general-purpose hook for fetching data from an API.
`useGet`	A specialized `useFetch` for making GET requests.
`useIdleFetch`	Triggers a data fetch when the user becomes active after a period of inactivity.
`useLocationBasedFetch`	Fetches data from an API based on the user's current geolocation.
`useMutation`	Manages asynchronous operations that modify data (e.g., POST, PUT, DELETE).
`useNetworkAwareFetch`	A `useFetch` variant that only runs when the user is online.
`usePatch`	A specialized `useFetch` for making PATCH requests.
`usePost`	A specialized `useFetch` for making POST requests.
`usePromise`	Manages the state of a promise-based function.
`usePut`	A specialized `useFetch` for making PUT requests.

4. Browser & Web APIs

Wrappers around platform APIs such as Clipboard, Storage, Battery, Permissions, and Web Workers.

Hook	Description
`useBatteryStatus`	Tracks the device's battery status using the Battery Status API.
`useBroadcastChannel`	Enables cross-tab/window communication using the Broadcast Channel API.
`useClipboard`	Interacts with the system clipboard for copying and pasting.
`useClipboardWithFeedback`	An extension of `useClipboard` that provides feedback when text is copied.
`useCookie`	Manages a specific browser cookie.
`useCopyToClipboard`	A hook specifically for copying text to the clipboard.
`useDeviceMotion`	Tracks device motion information like acceleration and rotation rate.
`useDeviceOrientation`	Tracks the physical orientation of the device.
`useDocumentTitle`	Sets the `document.title` of the page.
`useEventSource`	Connects to a Server-Sent Events (SSE) endpoint.
`useEyeDropper`	Uses the experimental EyeDropper API to sample colors from the screen.
`useFavicon`	Dynamically sets the website's favicon.
`useFullscreen`	Manages the fullscreen state for a specific element.
`useGeolocation`	Tracks the user's geolocation.
`useGeolocationContinuous`	Provides a continuous stream of geolocation data.
`useIdleCallback`	Schedules a function to be executed during browser idle periods.
`useIdleDetection`	Detects user idle state and screen lock status using the Idle Detection API.
`useLocalStorage`	Manages state with `localStorage`, automatically syncing between state and storage.
`useLocalStorageQueue`	Manages a queue that is persisted in `localStorage`.
`useLocalStorageValue`	Manages a single `localStorage` key.
`useMediaStream`	Manages access to the user's media devices (camera, microphone).
`useNetworkAwareWebSocket`	Manages a WebSocket connection that is only active when the user is online.
`useNetworkSpeed`	Gets information about the user's network connection speed and type.
`useNetworkState`	Tracks the state of the browser's network connection.
`useNotification`	Manages web notifications.
`useOnlineStatus`	Tracks the browser's online status.
`useOrientation`	Tracks the device's screen orientation.
`usePageVisibility`	Tracks the visibility state of the browser page/tab.
`usePermission`	Queries the status of a browser permission using the Permissions API.
`usePersistentCounter`	A counter that persists its state in `localStorage`.
`usePersistentToggle`	A boolean state that persists in `localStorage`.
`usePreferredLanguages`	Retrieves the user's preferred languages from the browser.
`usePrefersReducedMotion`	Detects if the user prefers reduced motion.
`useQueryParam`	Synchronizes a state variable with a URL query parameter.
`useScreenOrientation`	Tracks the screen orientation state.
`useScript`	Dynamically loads an external script and tracks its loading state.
`useSessionStorage`	Manages state with `sessionStorage`, automatically syncing between state and storage.
`useSpeechSynthesis`	Utilizes the browser's Speech Synthesis API (Text-to-Speech).
`useStorageValue`	A generic hook for managing a single key in a `Storage` object.
`useSyncedLocalStorage`	A `useLocalStorage` variant that syncs its state across multiple tabs/windows.
`useVibration`	Interacts with the browser's Vibration API.
`useWakeLock`	Manages a screen wake lock to prevent the device from sleeping.
`useWebSocket`	Manages WebSocket connections.
`useWebWorker`	Runs a function in a web worker to avoid blocking the main thread.
`useWorker`	Another hook for running functions in a web worker.
`useDarkMode`	Synchronizes the UI theme with system preferences and persists overrides in `localStorage`.
`useDebouncedGeolocation`	Throttles high-frequency geolocation updates so downstream effects run at a manageable cadence.

5. User Interface & DOM

DOM-centric hooks for layout measurements, interactions, viewport tracking, and accessibility patterns.

Hook	Description
`useBreakpoint`	Determines the currently active responsive breakpoint.
`useClickOutside`	Detects clicks outside of a specified element.
`useClickOutsideWithEscape`	Triggers a callback on a click outside an element or on pressing the 'Escape' key.
`useContextMenu`	Manages the state for a custom context menu.
`useDebouncedMediaQuery`	A `useMediaQuery` variant that debounces the result.
`useDebouncedWindowSize`	A `useWindowSize` variant that provides debounced dimensions.
`useDrag`	Provides basic drag-and-drop event handling for an element.
`useDraggable`	Makes a DOM element draggable.
`useElementSize`	Observes an element's size and provides its width and height.
`useFocusTrap`	Traps focus within a specified container element.
`useFocusWithinState`	Tracks whether an element or any of its descendants has focus.
`useHasBeenVisible`	Tracks if an element has ever become visible in the viewport.
`useHover`	Detects whether a DOM element is being hovered over.
`useHoverDelay`	Tracks if an element has been hovered for a minimum specified duration.
`useImageOnLoad`	Tracks the loading status and dimensions of an image.
`useInfiniteScroll`	Implements infinite scrolling.
`useIntersectionObserver`	Tracks the visibility of an element within the viewport.
`useMeasure`	Tracks element dimensions using `ResizeObserver`.
`useMediaQuery`	Tracks the state of a CSS media query.
`useMergeRefs`	Merges multiple refs into a single callback ref.
`useMobile`	Returns whether the current viewport is mobile-sized.
`useMousePosition`	Tracks the current position of the mouse pointer.
`usePageLeave`	Triggers a callback when the user's mouse cursor leaves the viewport.
`usePagination`	Manages pagination state and controls.
`usePinchZoom`	Detects pinch-to-zoom gestures on a target element.
`usePortal`	Manages a React Portal.
`useResizeObserver`	Monitors changes to an element's size using `ResizeObserver`.
`useRovingTabIndex`	Implements the roving tabindex accessibility pattern.
`useScrollLock`	Locks and unlocks body scroll.
`useScrollPosition`	Tracks the scroll position of the window or a specific element.
`useScrollSpy`	Monitors scroll position to determine which element is currently active.
`useScrollToTop`	Provides a function to scroll the window to the top.
`useSwipe`	Detects swipe gestures on a target element.
`useTextSelection`	Tracks the user's text selection within the document.
`useVirtualList`	Optimizes the rendering of long lists by only rendering visible items.
`useVisibility`	Tracks whether an element is visible in the viewport.
`useWindowSize`	Tracks the browser window's dimensions.
`useHookableRef`	Combines refs with callbacks so consumers can observe element mount/unmount events.
`useIsomorphicId`	Creates a stable ID that works consistently in SSR and CSR environments.

6. Event Handling

Utilities that simplify attaching listeners, key combos, long presses, and history changes.

Hook	Description
`useEventListener`	Attaches an event listener to a target element.
`useEventCallback`	Creates a stable callback function that always calls the latest version of the provided callback.
`useKeyCombo`	Detects specific keyboard combinations (shortcuts).
`useKeyPress`	Detects when a specific key is pressed down.
`useLongPress`	Detects long press events on an element.
`useRouteChange`	Executes a callback when the browser's route changes.
`useThrottledEventListener`	Attaches an event listener with a throttled callback.

7. Performance & Optimization

Debounce/throttle utilities, RAF helpers, and render diagnostics that keep components snappy.

Hook	Description
`useDebounce`	Debounces a value, delaying its update until a specified time has passed without change.
`useDebouncedCallback`	Creates a debounced version of a callback function.
`useDebouncedState`	A `useState` variant where the state updates are debounced.
`useForceUpdate`	Provides a function to manually force a component to re-render.
`useRafCallback`	Schedules a callback to be executed on the next animation frame.
`useRafState`	A `useState` variant that updates state on the next animation frame.
`useRenderCount`	Tracks the number of times a component has rendered.
`useRerender`	Provides a function to manually trigger a re-render.
`useThrottle`	Throttles a value, ensuring it updates at most once per specified interval.
`useThrottledCallback`	Creates a throttled version of a callback function.
`useThrottledScroll`	Tracks window scroll position with throttled updates.
`useThrottledState`	A `useState` variant where state updates are throttled.
`useCustomCompareMemo`	Memo variant that reruns its factory only when a custom comparator reports dependency changes.
`useSyncedRef`	Keeps a mutable ref in sync with the latest value without re-rendering consumers.

8. Forms

Form-centric hooks for managing inputs, validation, and lightweight i18n.

Hook	Description
`useForm`	Manages form state, input changes, and submission handling.
`useFormValidation`	Manages form state with built-in validation and submission logic.
`useTranslation`	A basic internationalization (i18n) hook for translating form labels and messages.

9. Timers & Intervals

Declarative abstractions over setTimeout and setInterval, including countdowns and idle timers.

Hook	Description
`useCountdown`	Manages a countdown timer with start, pause, and reset controls.
`useIdleTimer`	Detects user inactivity.
`useInterval`	Sets up an interval that repeatedly calls a function.
`useIntervalWhen`	An `useInterval` variant that only runs when a specific condition is true.
`useTimeout`	Sets up a timeout that calls a function after a delay.

10. Animation

Hooks powered by requestAnimationFrame for smooth motion primitives.

Hook	Description
`useAnimation`	Manages a basic animation loop using `requestAnimationFrame`.
`useAnimationFrame`	Runs a callback function repeatedly using `requestAnimationFrame`.

Package detail