@react-hookz/web Documentation

The library provides a wide range of general-purpose React hooks categorized by functionality:

• Callback: Debounced, throttled, or RAF-based callbacks (e.g., useDebouncedCallback, useRafCallback).
• Lifecycle: Specialized effect hooks (e.g., useMountEffect, useUpdateEffect, useIsomorphicLayoutEffect, useDeepCompareEffect).
• State: Advanced state management (e.g., useToggle, useList, useMap, useDebouncedState, usePrevious).
• Navigator: Browser-level state tracking (e.g., useNetworkState, usePermission).
• Side-effect: Async operations and storage management (e.g., useAsync, useCookieValue, useLocalStorageValue).
• Sensor: Browser APIs for observation (e.g., useIntersectionObserver, useMediaQuery, useWindowSize).
• Dom: DOM interaction (e.g., useClickOutside, useEventListener).
• Miscellaneous: Ref and memoization utilities (e.g., useSyncedRef, useDeepCompareMemo).

The useStorageValue hook accepts a UseStorageValueOptions object to customize how data is handled.

Default Behavior

By default, the hook uses JSON.parse for parse and JSON.stringify for stringify. It also attempts to initialize the state with the storage value immediately on the first render.

Custom Parsing and Stringifying

If you are storing non-JSON data (like a plain string or a custom format), provide your own functions:

useStorageValue(window.localStorage, 'user-name', {
  defaultValue: 'Guest',
  parse: (str) => (str === null ? 'Guest' : str),
  stringify: (val) => val,
});

Deferred Initialization

To avoid potential hydration mismatches in SSR (Server-Side Rendering) environments, set initializeWithValue: false. This ensures the hook returns undefined on the initial render, deferring the storage read until the component mounts in the browser.

const { value } = useStorageValue(window.localStorage, 'key', {
  initializeWithValue: false,
});

The useThrottledCallback hook returns a throttled version of a callback function. It ensures that the provided function is executed at most once every delay milliseconds. This is useful for limiting the execution rate of high-frequency events like scrolling, resizing, or mouse movements.

Parameters

• callback: The function to be throttled.
• deps: A dependency list (similar to useCallback) that determines when the throttled function should be updated.
• delay: The throttle delay in milliseconds.
• noTrailing (optional): A boolean that defaults to false.
  • If false (default), the callback will execute one final time after the last throttled call using the most recent arguments (trailing edge execution).
  • If true, the callback will only execute at the start of the delay period and will not execute a final time after the last call if it falls within the delay window.

The useConditionalEffect function accepts the following arguments:

The ListActions<T> object provides the following methods for manipulating the list:

The useStorageValue hook manages a piece of state that is automatically synchronized with web storage (such as localStorage or sessionStorage). It handles reading, writing, and listening to changes made to the storage key, even from other browser tabs.

Usage

Pass the storage object (e.g., window.localStorage), a unique key, and an optional options object to the hook. It returns an object containing the current value and several action methods: set, remove, and fetch.

Options

• defaultValue: The value to return if the key is not present in storage. Defaults to undefined.
• initializeWithValue: If true (default), the hook fetches the value from storage during the first render. If false, the hook yields undefined on the first render and fetches the value during the effect phase.
• parse: A custom function to parse the string retrieved from storage. Receives the raw string and the defaultValue as arguments.
• stringify: A custom function to convert the value into a string for storage. Defaults to JSON.stringify behavior.

API Result

The hook returns a UseStorageValueResult object:

• value: The current state of the stored item.
• set(value): Updates the state and persists the new value to storage.
• remove(): Deletes the item from storage.
• fetch(): Manually triggers a re-fetch of the value from storage.