\n\n[sponsor-badge]: https://img.shields.io/static/v1?label=Fund%20this%20package&message=%E2%9D%A4&logo=GitHub&color=%23DB61A2\n[sponsor-url]: https://github.com/sponsors/alessiofrittoli\n\n### Table of Contents\n\n- [Getting started](#getting-started)\n- [ESLint Configuration](#eslint-configuration)\n- [What's Changed](#whats-changed)\n- [API Reference](#api-reference)\n - [Browser API](#browser-api)\n - [`useStorage`](#usestorage)\n - [`useLocalStorage`](#uselocalstorage)\n - [`useSessionStorage`](#usesessionstorage)\n - [`useConnection`](#useconnection)\n - [`useDarkMode`](#usedarkmode)\n - [`useEventListener`](#useeventlistener)\n - [`useIsPortrait`](#useisportrait)\n - [`useIsTouchDevice`](#useistouchdevice)\n - [`useMediaQuery`](#usemediaquery)\n - [`usePreventContextMenu`](#usepreventcontextmenu)\n - [`useDocumentVisibility`](#usedocumentvisibility)\n - [`useWakeLock`](#usewakelock)\n - [DOM API](#dom-api)\n - [`useFocusTrap`](#usefocustrap)\n - [`useInView`](#useinview)\n - [`useScrollBlock`](#usescrollblock)\n - [Miscellaneous](#miscellaneous)\n - [`useInput`](#useinput)\n - [`useDeferCallback`](#usedefercallback)\n - [`useEffectOnce`](#useeffectonce)\n - [`useUpdateEffect`](#useupdateeffect)\n - [`useIsClient`](#useisclient)\n - [`useIsFirstRender`](#useisfirstrender)\n - [`usePagination`](#usepagination)\n - [`useSelection`](#useselection)\n - [Queue](#queue)\n - [Queue Types](#queue-types)\n - [Queue Utils](#queue-utils)\n - [`useShuffle`](#useshuffle)\n - [`useQueue`](#usequeue)\n - [Timers](#timers)\n - [`useDebounce`](#usedebounce)\n - [`useInterval`](#useinterval)\n - [`useIntervalWhenVisible`](#useintervalwhenvisible)\n - [`useLightInterval`](#uselightinterval)\n - [`useTimeout`](#usetimeout)\n - [`useLightTimeout`](#uselighttimeout)\n- [Development](#development)\n - [Install dependencies](#install-dependencies)\n - [Build the source code](#build-the-source-code)\n - [ESLint](#eslint)\n - [Jest](#jest)\n- [Contributing](#contributing)\n- [Security](#security)\n- [Credits](#made-with-)\n\n---\n\n### Getting started\n\nRun the following command to start using `react-hooks` in your projects:\n\n```bash\nnpm i @alessiofrittoli/react-hooks\n```\n\nor using `pnpm`\n\n```bash\npnpm i @alessiofrittoli/react-hooks\n```\n\n---\n\n### ESLint Configuration\n\nThis library may define and exports hooks that requires additional ESLint configuration for your project such as [`useUpdateEffect`](#useupdateeffect).\n\nSimply imports recommended configuration from `@alessiofrittoli/react-hooks/eslint` and add them to your ESLint configuration like so:\n\n```mjs\nimport { config as AFReactHooksEslint } from \"@alessiofrittoli/react-hooks/eslint\";\n\n/** @type {import('eslint').Linter.Config[]} */\nconst config = [\n ...AFReactHooksEslint.recommended,\n // ... other configurations\n];\n\nexport default config;\n```\n\n---\n\n### What's Changed\n\n#### Updates in the latest release 🎉\n\n- Added `useQueue` hook. See [API Reference](#usequeue) for more info.\n- Added `useShuffle` hook. See [API Reference](#useshuffle) for more info.\n\n---\n\nOld major updates\n\n- Added `usePreventContextMenu` hook. See [API Reference](#usepreventcontextmenu) for more info.\n- Improved `useConnection` hook. It now returns\n [`NetworkInformation`](https://github.com/alessiofrittoli/web-utils?tab=readme-ov-file#network-information) when available.\n See [API Reference](#useconnection) for more info.\n- Improved `useEventListener` hook types. It now supports `EventTarget` as listener targets.\n See [API Reference](#useeventlistener) for more info.\n- Added `useDocumentVisibility` hook. See [API Reference](#usedocumentvisibility) for more info.\n- Added `useWakeLock` hook. See [API Reference](#usewakelock) for more info.\n- Added `useDeferCallback` hook. See [API Reference](#usedefercallback) for more info.\n\n---\n\n### API Reference\n\n#### Browser API\n\n##### Storage\n\nThe following storage hooks use Storage Utilities from [`@alessiofrittoli/web-utils`](https://npmjs.com/package/@alessiofrittoli/web-utils#storage-utilities) adding a React oriented implementation.\n\n###### `useStorage`\n\nEasly handle Local or Session Storage State.\n\n\n\nType parameters\n\n| Parameter | Type | Default | Description |\n| --------- | ----- | -------- | ----------------------------------------- |\n| `T` | `any` | `string` | A custom type applied to the stored item. |\n\n\n\n---\n\n\n\nParameters\n\n| Parameter | Type | Default | Description |\n| --------- | ---------------- | ------- | ---------------------------------- |\n| `key` | `string` | - | The storage item key. |\n| `initial` | `T` | - | The storage item initial value. |\n| `type` | `local\\|session` | local | (Optional) The storage API to use. |\n\n\n\n---\n\n\n\nReturns\n\nType: `[ Value, SetValue> ]`\n\nA tuple with the stored item value or initial value and the setter function.\n\n\n\n---\n\n\n\nUsage\n\n###### Importing the hooks\n\n```tsx\nimport {\n useStorage,\n useLocalStorage,\n useSessionStorage,\n} from \"@alessiofrittoli/react-hooks\";\n```\n\n---\n\n###### Reading item value from storage\n\n```tsx\n'use client'\n\nimport { useStorage } from '@alessiofrittoli/react-hooks'\n\ntype Locale = 'it' | 'en'\n\nconst storage = 'local' // or 'session'\nconst defaultLocale = 'it'\n\nexport const SomeComponent: React.FC = () => {\n\n const [ userLocale ] = useStorage( 'user-locale', defaultLocale, storage )\n\n return (\n ...\n )\n\n}\n```\n\n---\n\n###### Updating storage item value\n\n```tsx\n'use client'\n\nimport { useCallback } from 'react'\nimport { useStorage } from '@alessiofrittoli/react-hooks'\n\ntype Locale = 'it' | 'en'\n\nconst storage = 'local' // or 'session'\nconst defaultLocale = 'it'\n\nexport const LanguageSwitcher: React.FC = () => {\n\n const [ userLocale, setUserLocale ] = useStorage( 'user-locale', defaultLocale, storage )\n\n const clickHandler = useCallback( () => {\n setUserLocale( 'en' )\n }, [ setUserLocale ] )\n\n return (\n ...\n )\n\n}\n```\n\n---\n\n###### Deleting storage item\n\n```tsx\n'use client'\n\nimport { useCallback } from 'react'\nimport { useStorage } from '@alessiofrittoli/react-hooks'\n\ntype Locale = 'it' | 'en'\n\nconst storage = 'local' // or 'session'\nconst defaultLocale = 'it'\n\nexport const LanguageSwitcher: React.FC = () => {\n\n const [ userLocale, setUserLocale ] = useStorage( 'user-locale', defaultLocale, storage )\n\n const deleteHandler = useCallback( () => {\n setUserLocale( null )\n // or\n setUserLocale( undefined )\n // or\n setUserLocale( '' )\n }, [ setUserLocale ] )\n\n return (\n ...\n )\n\n}\n```\n\n\n\n---\n\n###### `useLocalStorage`\n\nShortcut React Hook for [`useStorage`](#usestorage).\n\nApplies the same API Reference.\n\n---\n\n###### `useSessionStorage`\n\nShortcut React Hook for [`useStorage`](#usestorage).\n\nApplies the same API Reference.\n\n---\n\n##### `useConnection`\n\nGet states about Internet Connection.\n\n\n\nReturns\n\nType: `Connection`\n\nAn object defining network status and `NetworkInformation`.\n\n- See [`Connection`](https://github.com/alessiofrittoli/web-utils?tab=readme-ov-file#connection-interface) interface from [`@alessiofrittoli/web-utils`](https://www.npmjs.com/package/@alessiofrittoli/web-utils)\n\n\n\n---\n\n##### `useDarkMode`\n\nEasily manage dark mode with full respect for user device preferences.\n\nThis hook is user-oriented and built to honor system-level color scheme settings:\n\n- If the device prefers a dark color scheme, dark mode is automatically enabled on first load.\n- If the user enables/disables dark mode via a web widget, the preference is stored in `localStorage` under the key `dark-mode`.\n- If the device color scheme preference changes (e.g. via OS settings), that change takes precedence and is stored for future visits.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| ----------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |\n| `options` | `UseDarkModeOptions` | (Optional) Configuration object for the hook. |\n| `options.initial` | `boolean` | (Optional) The fallback value to use if no preference is saved in `localStorage`. Defaults to `true` if the device prefers dark mode. |\n| `options.docClassNames` | `[dark: string, light: string]` | (Optional) Array of class names to toggle on the `` element, e.g. `['dark', 'light']`. |\n\n\n\n---\n\n\n\nReturns\n\nType: `UseDarkModeOutput`\n\nAn object containing utilities for managing dark mode:\n\n- `isDarkMode`: `boolean` — Whether dark mode is currently enabled.\n- `isDarkOS`: `boolean` — Whether the user's system prefers dark mode.\n- `toggleDarkMode`: `() => void` — Toggles dark mode and saves the preference.\n- `enableDarkMode`: `() => void` — Enables dark mode and saves the preference.\n- `disableDarkMode`: `() => void` — Disables dark mode and saves the preference.\n\n\n\n---\n\n\n\nUsage\n\n###### Basic usage\n\n```tsx\n\"use client\";\n\nimport { useDarkMode } from \"@alessiofrittoli/react-hooks\";\n\nexport const Component: React.FC = () => {\n const { isDarkMode } = useDarkMode();\n\n return
;\n};\n```\n\n```css\n/* style.css */\n.light {\n color-scheme: light;\n}\n\n.dark {\n color-scheme: dark;\n}\n\n.light body {\n color: black;\n background: white;\n}\n\n.dark body {\n color: white;\n background: black;\n}\n```\n\n---\n\n###### Custom theme switcher\n\n```tsx\n\"use client\";\n\nimport { useDarkMode } from \"@alessiofrittoli/react-hooks\";\n\nexport const ThemeSwitcher: React.FC = () => {\n const { isDarkMode, toggleDarkMode } = useDarkMode();\n\n return ;\n};\n```\n\n---\n\n###### Sync Document theme-color for consistent browser styling\n\nBrowsers automatically apply colorization using:\n\n```html\n\n```\n\nThis works based on the OS preference — _not your site theme_. That can cause mismatches if, for example, the system is in dark mode but the user disabled dark mode via a web toggle.\n\nTo ensure consistency, `useDarkMode` updates these meta tags dynamically based on the actual mode.\n\nJust make sure to define both `light` and `dark` theme-color tags in your document:\n\n```html\n\n \n \n\n```\n\n\n\n---\n\n##### `useEventListener`\n\nAttach a new Event listener to the `Window`, `Document`, `MediaQueryList` or an `HTMLElement`.\n\n\n\nParameters\n\n\n\nWindow events\n\n| Parameter | Type | Description |\n| ------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `type` | `K\\|K[]` | The `Window` event name or an array of event names. |\n| | | ⚠️ Please, make sure to memoize the event names array with `useMemo` |\n| | | or declare that array outside your Component/hook in order to avoid infinite loops when a React state changes. |\n| `options` | `WindowListenerOptions` | An object defining init options. |\n| `options.listener` | `WindowEventListener` | The Window Event listener. |\n| `options.onLoad` | `() => void` | A custom callback executed before event listener get attached. |\n| `options.onCleanUp` | `() => void` | A custom callback executed after event listener get removed. |\n| `options.options` | `ListenerOptions` | Specifies characteristics about the event listener. See [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options). |\n\n\n\n---\n\n\n\nDocument events\n\n| Parameter | Type | Description |\n| ------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `type` | `K\\|K[]` | The `Document` event name or an array of event names. |\n| | | ⚠️ Please, make sure to memoize the event names array with `useMemo` |\n| | | or declare that array outside your Component/hook in order to avoid infinite loops when a React state changes. |\n| `options` | `DocumentListenerOptions` | An object defining init options. |\n| `options.target` | `Document\\|null\\|React.RefObject` | The `Document` reference or a React RefObject of the `Document`. |\n| `options.listener` | `DocumentEventListener` | The Document Event listener. |\n| `options.onLoad` | `() => void` | A custom callback executed before event listener get attached. |\n| `options.onCleanUp` | `() => void` | A custom callback executed after event listener get removed. |\n| `options.options` | `ListenerOptions` | Specifies characteristics about the event listener. See [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options). |\n\n\n\n---\n\n\n\nHTMLElement events\n\n| Parameter | Type | Description |\n| ------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `type` | `K\\|K[]` | The `HTMLElement` event name or an array of event names. |\n| | | ⚠️ Please, make sure to memoize the event names array with `useMemo` |\n| | | or declare that array outside your Component/hook in order to avoid infinite loops when a React state changes. |\n| `options` | `ElementListenerOptions` | An object defining init options. |\n| `options.target` | `T\\|React.RefObject` | The React RefObject of the target where the listener get attached to. |\n| `options.listener` | `ElementEventListener` | The HTMLElement Event listener. |\n| `options.onLoad` | `() => void` | A custom callback executed before event listener get attached. |\n| `options.onCleanUp` | `() => void` | A custom callback executed after event listener get removed. |\n| `options.options` | `ListenerOptions` | Specifies characteristics about the event listener. See [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options). |\n\n\n\n---\n\n\n\nMediaQuery events\n\n| Parameter | Type | Description |\n| ------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `type` | `change` | The `MediaQueryList` event name. |\n| `options` | `MediaQueryListenerOptions` | An object defining init options. |\n| `options.query` | `string` | The Media Query string to check. |\n| `options.listener` | `MediaQueryChangeListener` | The MediaQueryList Event listener. |\n| `options.onLoad` | `() => void` | A custom callback executed before event listener get attached. |\n| `options.onCleanUp` | `() => void` | A custom callback executed after event listener get removed. |\n| `options.options` | `ListenerOptions` | Specifies characteristics about the event listener. See [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options). |\n\n\n\n---\n\n\n\nCustom events\n\n| Parameter | Type | Description |\n| ------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `type` | `K\\|K[]` | The custom event name or an array of event names. |\n| | | ⚠️ Please, make sure to memoize the event names array with `useMemo` |\n| | | or declare that array outside your Component/hook in order to avoid infinite loops when a React state changes. |\n| `options` | `CustomEventListenerOptions` | An object defining init options. |\n| `options.target` | `Document\\|EventTarget\\|HTMLElement\\|null\\|React.RefObject` | (Optional) The target where the listener get attached to. If not set, the listener will get attached to the `Window` object. |\n| `options.listener` | `( event: T[ K ] ) => void` | The Event listener. |\n| `options.onLoad` | `() => void` | A custom callback executed before event listener get attached. |\n| `options.onCleanUp` | `() => void` | A custom callback executed after event listener get removed. |\n| `options.options` | `ListenerOptions` | Specifies characteristics about the event listener. See [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options). |\n\n\n\n\n\n---\n\n\n\nUsage\n\n###### Attach listeners to the Window object\n\n```tsx\n'use client'\n\nimport { useCallback } from 'react'\nimport { useEventListener } from '@alessiofrittoli/react-hooks'\n\nexport const MyComponent: React.FC = () => {\n\n useEventListener( 'popstate', {\n listener: useCallback( event => {\n ...\n }, [] ),\n } )\n\n}\n```\n\n---\n\n###### Attach listeners to the Document object\n\n```tsx\n'use client'\n\nimport { useCallback } from 'react'\nimport { useEventListener } from '@alessiofrittoli/react-hooks'\n\nexport const MyComponent: React.FC = () => {\n\n useEventListener( 'click', {\n target : typeof document !== 'undefined' ? document : null,\n listener : useCallback( event => {\n ...\n }, [] ),\n } )\n\n}\n```\n\n---\n\n###### Attach listeners to an HTMLElement\n\n```tsx\n'use client'\n\nimport { useCallback, useRef } from 'react'\nimport { useEventListener } from '@alessiofrittoli/react-hooks'\n\nexport const MyComponent: React.FC = () => {\n\n const buttonRef = useRef( null )\n\n useEventListener( 'click', {\n target: buttonRef,\n listener: useCallback( event => {\n ...\n }, [] ),\n } )\n\n return (\n \n )\n\n}\n```\n\n---\n\n###### Attach listeners to a MediaQueryList\n\n```tsx\nimport { useCallback } from 'react'\nimport { useEventListener } from '@alessiofrittoli/react-hooks'\n\nexport const MyComponent: React.FC = () => {\n\n useEventListener( 'change', {\n query : '(max-width: 768px)',\n listener : useCallback( event => {\n if ( event.matches ) {\n ...\n }\n }, [] )\n } )\n\n}\n```\n\n---\n\n###### Listen dispatched custom events\n\n```tsx\nimport { useCallback } from 'react'\nimport { useEventListener } from '@alessiofrittoli/react-hooks'\n\nclass CustomEvent extends Event\n{\n isCustom: boolean\n\n constructor( type: string, eventInitDict?: EventInit )\n {\n super( type, eventInitDict )\n this.isCustom = true\n }\n}\n\n\ntype CustomEventMap = {\n customEventName: CustomEvent\n}\n\n\nexport const MyComponent: React.FC = () => {\n\n const clickHandler = useCallback( () => {\n document.dispatchEvent( new CustomEvent( 'customEventName' ) )\n }, [] )\n\n useEventListener( 'customEventName', {\n target : typeof document !== 'undefined' ? document : null,\n listener : useCallback( event => {\n if ( event.isCustom ) {\n ...\n }\n }, [] )\n } )\n\n\n return (\n \n )\n\n}\n```\n\n---\n\n###### Attach listeners to multiple events\n\n```tsx\nimport { useCallback, useState } from \"react\";\nimport { useEventListener } from \"@alessiofrittoli/react-hooks\";\n\n/**\n * We define events outside the Component to avoid array recreation when a state update is triggered.\n *\n * This prevents infinite loops for `useEventListener` life-cycle\n */\nconst events: (keyof WindowEventMap)[] = [\"resize\", \"scroll\"];\n\nexport const MyComponent: React.FC = () => {\n const [isInteracting, setIsIntercting] = useState(false);\n\n useEventListener(events, {\n listener: useCallback(() => {\n setIsIntercting(true);\n }, []),\n });\n};\n```\n\n\n\n---\n\n##### `useIsPortrait`\n\nCheck if device is portrait oriented.\n\nReact State get updated when device orientation changes.\n\n\n\nReturns\n\nType: `boolean`\n\n- `true` if the device is portrait oriented.\n- `false` otherwise.\n\n\n\n---\n\n\n\nUsage\n\n###### Check if user device is in landscape\n\n```tsx\nimport { useIsPortrait } from \"@alessiofrittoli/react-hooks\";\n\nconst isLandscape = !useIsPortrait();\n```\n\n\n\n---\n\n##### `useIsTouchDevice`\n\nDetects if the current device supports touch events.\n\n\n\nReturns\n\nType: `boolean`\n\n- `true` if the device is touch device.\n- `false` otherwise.\n\n\n\n---\n\n\n\nUsage\n\n```tsx\nimport { useIsTouchDevice } from \"@alessiofrittoli/react-hooks\";\n\nconst isTouchDevice = useIsTouchDevice();\n```\n\n\n\n---\n\n##### `useMediaQuery`\n\nGet Document Media matches and listen for changes.\n\n\n\nParameters\n\n| Parameter | Type | Default | Description |\n| --------------------- | ------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |\n| `query` | `string` | - | A string specifying the media query to parse into a `MediaQueryList`. |\n| `options` | `UseMediaQueryOptions\\|UseMediaQueryStateOptions` | - | An object defining custom options. |\n| `options.updateState` | `boolean` | `true` | Indicates whether the hook will dispatch a React state update when the given `query` change event get dispatched. |\n| `options.onChange` | `OnChangeHandler` | - | A custom callback that will be invoked on initial page load and when the given `query` change event get dispatched. |\n| | | | This callback is required if `updateState` is set to `false`. |\n\n\n\n---\n\n\n\nReturns\n\nType: `boolean|void`\n\n- `true` or `false` if the document currently matches the media query list or not.\n- `void` if `updateState` is set to `false`.\n\n\n\n---\n\n\n\nUsage\n\n###### Check if user device prefers dark color scheme\n\n```tsx\nimport { useMediaQuery } from \"@alessiofrittoli/react-hooks\";\n\nconst isDarkOS = useMediaQuery(\"(prefers-color-scheme: dark)\");\n```\n\n---\n\n###### Listen changes with no state updates\n\n```tsx\nimport { useMediaQuery } from \"@alessiofrittoli/react-hooks\";\n\nuseMediaQuery(\"(prefers-color-scheme: dark)\", {\n updateState: false,\n onChange(matches) {\n console.log(\"is dark OS?\", matches);\n },\n});\n```\n\n\n\n---\n\n##### `usePreventContextMenu`\n\nPrevents the context menu from appearing on a specified target element.\n\n\n\nParameters\n\n| Parameter | Type | Default | Description |\n| --------- | ----------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------- |\n| `target` | `EventListenerTarget\\|React.RefObject` | `window` | The target element or a `React.RefObject` where the context menu should be prevented. |\n| | | | If not provided, the listener will be attached to the top `window`. |\n\n\n\n---\n\n\n\nExamples\n\n```tsx\n// Prevent context menu on the entire top window.\nusePreventContextMenu();\n\n// Prevent context menu on a specific target.\nconst ref = useRef(null);\nusePreventContextMenu(ref);\n```\n\n\n\n---\n\n##### `useDocumentVisibility`\n\nTrack the visibility state of the document (i.e., whether the page is visible or hidden).\n\n\n\nParameters\n\n| Parameter | Type | Default | Description |\n| ---------------------------- | ------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------- |\n| `options` | `UseDocumentVisibilityOptions\\|StateDisabledUseDocumentVisibilityOptions` | - | Configuration options for the hook. |\n| `options.updateState` | `boolean` | `true` | Whether to update React state about Document visibility state or not. |\n| `options.onVisibilityChange` | `VisibilityChangeHandler` | - | A custom callback executed when Document visiblity sate changes. |\n\n\n\n---\n\n\n\nReturns\n\nType: `boolean | void`\n\nReturns `true` if the document is visible, `false` if hidden, or `void` if `updateState` is set to `false`.\n\n\n\n---\n\n\n\nUsage\n\n###### Simple usage\n\n```tsx\nimport { useDocumentVisibility } from \"@alessiofrittoli/react-hooks\";\n\nconst isDocumentVisible = useDocumentVisibility();\n```\n\n---\n\n###### Disable state updates and listen visibility changes\n\n```tsx\nimport {\n useDocumentVisibility,\n type VisibilityChangeHandler,\n} from \"@alessiofrittoli/react-hooks\";\n\nconst onVisibilityChange = useCallback((isVisible) => {\n // ... do something\n}, []);\nuseDocumentVisibility({ updateState: false, onVisibilityChange });\n```\n\n\n\n---\n\n##### `useWakeLock`\n\nEasily manage the [Screen Wake Lock API](https://developer.mozilla.org/en-US/docs/Web/API/Screen_Wake_Lock_API) to prevent the device screen from dimming or locking while your app is in use.\n\n\n\nParameters\n\n| Parameter | Type | Default | Description |\n| ----------------- | ------------------------ | ------- | ---------------------------------------------------------------- |\n| `options` | `UseWakeLockOptions` | - | (Optional) An object defining hook options. |\n| `options.onMount` | `boolean` | `true` | Indicates whether to request the screen WakeLock on mount. |\n| `options.onError` | `OnWakeLockRequestError` | - | A custom callback executed when a screen WakeLock request fails. |\n\n\n\n---\n\n\n\nReturns\n\nType: `UseWakeLock`\n\nAn object returning The current `WakeLockSentinel` instance or `null` if not enabled and utility functions.\n\n- `wakeLock`: `WakeLockSentinel | null` — The current Wake Lock instance, or null if not enabled.\n- `enabled`: `boolean` — Whether the Wake Lock is currently active.\n- `requestWakeLock`: `() => Promise` — Manually request the Wake Lock.\n- `releaseWakeLock`: `() => Promise` — Manually release the Wake Lock.\n\n\n\n---\n\n\n\nUsage\n\n###### Enable Wake Lock on mount\n\n```tsx\nimport { useWakeLock } from \"@alessiofrittoli/react-hooks\";\n\nuseWakeLock();\n```\n\n---\n\n###### Manually enable and disable Wake Lock\n\n```tsx\nimport { useWakeLock } from \"@alessiofrittoli/react-hooks\";\n\nexport const WakeLockButton: React.FC = () => {\n const { enabled, requestWakeLock, releaseWakeLock } = useWakeLock({\n enableOnLoad: false,\n });\n\n return (\n <>\n
Wakelock enabled: {enabled.toString()}
\n \n \n \n );\n};\n```\n\n---\n\n###### Handling Wake Lock errors\n\n```tsx\nimport {\n useWakeLock,\n type OnWakeLockRequestError,\n} from \"@alessiofrittoli/react-hooks\";\n\nconst onError: OnWakeLockRequestError = (error) => {\n alert(\"Could not enable Wake Lock: \" + error.message);\n};\n\nexport const WakeLockWithError: React.FC = () => {\n const { enabled, requestWakeLock } = useWakeLock({ onError });\n\n return (\n \n );\n};\n```\n\n\n\n---\n\n#### DOM API\n\n##### `useFocusTrap`\n\nTrap focus inside the given HTML Element.\n\nThis comes pretty handy when rendering a modal that shouldn't be closed without a user required action.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | ------------------------------------ | ------------------------------------------------------------------------------------------- |\n| `target` | `React.RefObject` | The target HTMLElement React RefObject to trap focus within. |\n| | | If no target is given, you must provide the target HTMLElement when calling `setFocusTrap`. |\n\n\n\n---\n\n\n\nReturns\n\nType: `readonly [ SetFocusTrap, RestoreFocusTrap ]`\n\nA tuple containing:\n\n- `setFocusTrap`: A function to enable the focus trap. Optionally accept an HTMLElement as target.\n- `restoreFocusTrap`: A function to restore the previous focus state.\n\n\n\n---\n\n\n\nUsage\n\n###### Defining the target on hook initialization\n\n```tsx\nimport { useFocusTrap } from \"@alessiofrittoli/react-hooks\";\n\nconst modalRef = useRef(null);\nconst [setFocusTrap, restoreFocusTrap] = useFocusTrap(modalRef);\n\nconst modalOpenHandler = useCallback(() => {\n if (!modalRef.current) return;\n // ... open modal\n setFocusTrap();\n modalRef.current.focus(); // focus the dialog so next tab will focus the next element inside the modal\n}, [setFocusTrap]);\n\nconst modalCloseHandler = useCallback(() => {\n // ... close modal\n restoreFocusTrap(); // cancel focus trap and restore focus to the last active element before enablig the focus trap\n}, [restoreFocusTrap]);\n```\n\n---\n\n###### Defining the target ondemand\n\n```tsx\nimport { useFocusTrap } from \"@alessiofrittoli/react-hooks\";\n\nconst modalRef = useRef(null);\nconst modal2Ref = useRef(null);\nconst [setFocusTrap, restoreFocusTrap] = useFocusTrap();\n\nconst modalOpenHandler = useCallback(() => {\n if (!modalRef.current) return;\n // ... open modal\n setFocusTrap(modalRef.current);\n modalRef.current.focus();\n}, [setFocusTrap]);\n\nconst modal2OpenHandler = useCallback(() => {\n if (!modal2Ref.current) return;\n // ... open modal\n setFocusTrap(modal2Ref.current);\n modal2Ref.current.focus();\n}, [setFocusTrap]);\n```\n\n\n\n---\n\n##### `useInView`\n\nCheck if the given target Element is intersecting with an ancestor Element or with a top-level document's viewport.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `target` | `React.RefObject` | The React.RefObject of the target Element to observe. |\n| `options` | `UseInViewOptions` | (Optional) An object defining custom `IntersectionObserver` options. |\n| `options.root` | `Element\\|Document\\|false\\|null` | (Optional) Identifies the `Element` or `Document` whose bounds are treated as the bounding box of the viewport for the Element which is the observer's target. |\n| `options.margin` | `MarginType` | (Optional) A string, formatted similarly to the CSS margin property's value, which contains offsets for one or more sides of the root's bounding box. |\n| `options.amount` | `'all'\\|'some'\\|number\\|number[]` | (Optional) The intersecting target thresholds. |\n| | | Threshold can be set to: |\n| | | - `all` - `1` will be used. |\n| | | - `some` - `0.5` will be used. |\n| | | - `number` |\n| | | - `number[]` |\n| `options.once` | `boolean` | (Optional) By setting this to `true` the observer will be disconnected after the target Element enters the viewport. |\n| `options.initial` | `boolean` | (Optional) Initial value. This value is used while server rendering then will be updated in the client based on target visibility. Default: `false`. |\n| `options.enable` | `boolean` | (Optional) Defines the initial observation activity. Use the returned `setEnabled` to update this state. Default: `true`. |\n| `options.onIntersect` | `OnIntersectStateHandler` | (Optional) A custom callback executed when target element's visibility has crossed one or more thresholds. |\n| | | This callback is awaited before any state update. |\n| | | If an error is thrown the React State update won't be fired. |\n| | | ⚠️ Wrap your callback with `useCallback` to avoid unnecessary `IntersectionObserver` recreation. |\n| `options.onEnter` | `OnIntersectHandler` | (Optional) A custom callback executed when target element's visibility has crossed one or more thresholds. |\n| | | This callback is awaited before any state update. |\n| | | If an error is thrown the React State update won't be fired. |\n| | | ⚠️ Wrap your callback with `useCallback` to avoid unnecessary `IntersectionObserver` recreation. |\n| `options.onExit` | `OnIntersectHandler` | (Optional) A custom callback executed when target element's visibility has crossed one or more thresholds. |\n| | | This callback is awaited before any state update. |\n| | | If an error is thrown the React State update won't be fired. |\n| | | ⚠️ Wrap your callback with `useCallback` to avoid unnecessary `IntersectionObserver` recreation. |\n\n\n\n---\n\n\n\nReturns\n\nType: `UseInViewReturnType`\n\nAn object containing:\n\n- `inView`: `boolean` - Indicates whether the target Element is in viewport or not.\n- `setInView`: `React.Dispatch>` - A React Dispatch SetState action that allows custom state updates.\n- `enabled`: `boolean` - Indicates whether the target Element is being observed or not.\n- `setEnabled`: `React.Dispatch>` - A React Dispatch SetState action that allows to enable/disable observation when needed.\n- `observer`: `IntersectionObserver | undefined` - The `IntersectionObserver` instance. It could be `undefined` if `IntersectionObserver` is not available or observation is not enabled.\n\n\n\n---\n\n\n\nUsage\n\n###### Basic usage\n\n```tsx\n\"use client\";\n\nimport { useRef } from \"react\";\nimport { useInView } from \"@alessiofrittoli/react-hooks\";\n\nconst UseInViewExample: React.FC = () => {\n const targetRef = useRef(null);\n const { inView } = useInView(ref);\n\n return Array.from(Array(6)).map((value, index) => (\n \n \n {index + 1}\n \n \n ));\n};\n```\n\n---\n\n###### Disconnect observer after target enters the viewport\n\n```tsx\n\"use client\";\n\nimport { useRef } from \"react\";\nimport { useInView } from \"@alessiofrittoli/react-hooks\";\n\nconst OnceExample: React.FC = () => {\n const targetRef = useRef(null);\n const { inView } = useInView(targetRef, { once: true });\n\n useEffect(() => {\n if (!inView) return;\n console.count(\"Fired only once: element entered viewport.\");\n }, [inView]);\n\n return (\n \n );\n};\n```\n\n---\n\n###### Observe target only when needed\n\n```tsx\n\"use client\";\n\nimport { useRef } from \"react\";\nimport { useInView } from \"@alessiofrittoli/react-hooks\";\n\nconst OnDemandObservation: React.FC = () => {\n const targetRef = useRef(null);\n const { inView, enabled, setEnabled } = useInView(targetRef, {\n enable: false,\n });\n\n return (\n
\n \n \n
\n );\n};\n```\n\n---\n\n###### Execute custom callback when intersection occurs\n\n```tsx\n\"use client\";\n\nimport { useRef } from \"react\";\nimport {\n useInView,\n type OnIntersectStateHandler,\n} from \"@alessiofrittoli/react-hooks\";\n\nconst AsyncStartExample: React.FC = () => {\n const targetRef = useRef(null);\n const onIntersect = useCallback(\n async ({ entry, isEntering }) => {\n if (isEntering) {\n console.log(\"Delaying state update...\");\n await new Promise((resolve) => setTimeout(resolve, 1000)); // Simulate delay\n console.log(\"Async task completed. `inView` will now be updated.\");\n return;\n }\n\n console.log(\"Delaying state update...\");\n await new Promise((resolve) => setTimeout(resolve, 1000)); // Simulate delay\n console.log(\"Async task completed. `inView` will now be updated.\");\n },\n [],\n );\n\n const { inView } = useInView(targetRef, { onIntersect });\n\n return (\n \n );\n};\n```\n\n---\n\n###### Execute custom callback when `onEnter` and `onExit`\n\n```tsx\n\"use client\";\n\nimport { useRef } from \"react\";\nimport {\n useInView,\n type OnIntersectHandler,\n} from \"@alessiofrittoli/react-hooks\";\n\nconst AsyncStartExample: React.FC = () => {\n const targetRef = useRef(null);\n const onEnter = useCallback(async ({ entry }) => {\n console.log(\"In viewport - \", entry);\n }, []);\n const onExit = useCallback(async ({ entry }) => {\n console.log(\"Exited viewport - \", entry);\n }, []);\n\n const { inView } = useInView(targetRef, { onEnter, onExit });\n\n return (\n \n );\n};\n```\n\n\n\n---\n\n##### `useScrollBlock`\n\nPrevent Element overflow.\n\n\n\nParameters\n\n| Parameter | Type | Default | Description |\n| --------- | ------------------------------------ | -------------------------- | -------------------------------------------------- |\n| `target` | `React.RefObject` | `Document.documentElement` | (Optional) The React RefObject target HTMLElement. |\n\n\n\n---\n\n\n\nReturns\n\nType: `[ () => void, () => void ]`\n\nA tuple with block and restore scroll callbacks.\n\n\n\n---\n\n\n\nUsage\n\n###### Block Document Overflow\n\n```tsx\nimport { useScrollBlock } from '@alessiofrittoli/react-hooks'\n\nconst [ blockScroll, restoreScroll ] = useScrollBlock()\n\nconst openPopUpHandler = useCallback( () => {\n ...\n blockScroll()\n}, [ blockScroll ] )\n\nconst closePopUpHandler = useCallback( () => {\n ...\n restoreScroll()\n}, [ restoreScroll ] )\n\n...\n```\n\n---\n\n###### Block HTML Element Overflow\n\n```tsx\nconst elementRef = useRef( null )\n\nconst [ blockScroll, restoreScroll ] = useScrollBlock( elementRef )\n\nconst scrollBlockHandler = useCallback( () => {\n ...\n blockScroll()\n}, [ blockScroll ] )\n\nconst scrollRestoreHandler = useCallback( () => {\n ...\n restoreScroll()\n}, [ restoreScroll ] )\n\n...\n```\n\n\n\n---\n\n#### Miscellaneous\n\n##### `useInput`\n\nHandle input states with ease.\n\n\n\nType Parameters\n\n| Parameter | Description |\n| --------- | ---------------------- |\n| `I` | The input value type. |\n| `O` | The output value type. |\n\n\n\n---\n\n\n\nParameters\n\n| Parameter | Type | Default | Description |\n| ---------------------- | ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `options` | `UseInputOptions` | `{}` | An object defining custom options. |\n| `options.inputRef` | `React.RefObject` | - | (Optional) The React HTML input element ref. |\n| `options.initialValue` | `O\\|null` | - | (Optional) The input initial value. |\n| `options.touchTimeout` | `number` | 600 | (Optional) A timeout in milliseconds which will be used to define the input as \"touched\" thus validations are triggered and errors can be displayed. |\n| `options.validate` | `ValidateValueHandler` | - | (Optional) Value validation handler. If `parse` callback is given, the `value` will be parsed before validation. |\n| `options.parse` | `ParseValueHandler` | - | (Optional) Parse value. |\n| `options.onChange` | `ChangeHandler` | - | (Optional) A callable function executed when the `ChangeEvent` is dispatched on the HTML input element. |\n\n\n\n---\n\n\n\nReturns\n\nType: `UseInputOutput`\n\nAn object containing the following properties:\n\n| Property | Type | Description |\n| --------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |\n| `isEmpty` | `boolean` | Indicates whether the Input is empty or not. |\n| `hasError` | `boolean` | Indicates whether the input has error or not. |\n| | | It will return true if the Input does not pass the validation checks and it has been touched. |\n| | | Please refer to the `isValid` property to check the Input validity regardless of whether it has been touched or not. |\n| `changeHandler` | `React.ChangeEventHandler` | Change handler callback used to handle Input change events. |\n| `blurHandler` | `() => void` | Blur handler callback used to handle Input blur events. |\n| `setValue` | `( value: O ) => void` | Call `setValue` method to update input value. |\n| `submit` | `() => void` | Call `submit` method to re-run validations and ensure error state is updated successfully. |\n| `reset` | `() => void` | Call `reset` method to reset the Input state. |\n| `focus` | `() => void` | Call `focus` method to focus the Input Element. `inputRef` must be provided in the input options. |\n\n\n\n---\n\n\n\nUsage\n\n###### Basic usage\n\n```tsx\nconst MyComponent: React.FC = () => {\n const input = useInput();\n\n return (\n \n );\n};\n```\n\n---\n\n###### Displaying custom error messages\n\n```tsx\nimport {\n useInput,\n type ValidateValueHandler,\n} from \"@alessiofrittoli/react-hooks\";\n\nconst isNotEmpty: ValidateValueHandler = (value) =>\n !value ? false : value.trim().length > 0;\n\nconst MyComponent: React.FC = () => {\n const input = useInput({\n validate: isNotEmpty,\n });\n\n return (\n <>\n \n {input.hasError && The input cannot be empty.}\n \n );\n};\n```\n\n---\n\n###### Parsing and validating parsed value\n\n```tsx\nimport { formatDate, isValidDate } from \"@alessiofrittoli/date-utils\";\nimport {\n useInput,\n type ValidateValueHandler,\n type ParseValueHandler,\n} from \"@alessiofrittoli/react-hooks\";\n\nconst parseStringToDate: ParseValueHandler = (value) =>\n value ? new Date(value) : undefined;\n\nconst validateInputDate: ValidateValueHandler = (value) =>\n isValidDate(value) && value.getTime() > Date.now();\n\nconst MyComponent: React.FC = () => {\n const input = useInput({\n parse: parseStringToDate,\n validate: validateInputDate,\n });\n\n return (\n <>\n \n {input.hasError && (\n Please choose a date no earlier than today\n )}\n \n );\n};\n```\n\n\n\n---\n\n##### `useDeferCallback`\n\n`useDeferCallback` will return a memoized and deferred version of the callback that only changes if one of the `inputs` in the dependency list has changed.\n\nSince [`deferCallback`](https://npmjs.com/package/@alessiofrittoli/web-utils?activeTab=readme#deferCallback) returns a new function when called, it may cause your child components to uselessly re-validate when a state update occurs in the main component.\nTo avoid these pitfalls you can memoize and defer your task with `useDeferCallback`.\n\nTake a look at [`deferTask`](https://npmjs.com/package/@alessiofrittoli/web-utils?activeTab=readme#deferTask) to defer single tasks in a function handler.\n\n\n\nType Parameters\n\n| Parameter | Description |\n| --------- | ------------------------------------------------------------------------------------------------- |\n| `T` | The task function definition. `unknown` types will be inherited by your function type definition. |\n| `U` | The task function arguments. `unknown` types will be inherited by your function type. |\n\n\n\n---\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | ---- | --------------------------- |\n| `task` | `T` | The task callable function. |\n\n\n\n---\n\n\n\nReturns\n\nType: `( ...args: U ) => Promise>>`\n\nA new memoized handler which returns a new Promise that returns the `task` result once fulfilled.\n\n\n\n---\n\n\n\nUsage\n\n```tsx\nconst MyComponent: React.FC = () => {\n\n const clickHandler = useDeferCallback(\n event => { ... }, []\n )\n\n return (\n \n )\n\n}\n```\n\n\n\n---\n\n##### `useEffectOnce`\n\nModified version of `useEffect` that only run once on intial load.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | ---------------------- | ------------------------------------------------------- |\n| `effect` | `React.EffectCallback` | Imperative function that can return a cleanup function. |\n\n\n\n---\n\n\n\nUsage\n\n```tsx\n\"use client\";\n\nimport { useEffect, useState } from \"react\";\nimport { useEffectOnce } from \"@alessiofrittoli/react-hooks\";\n\nexport const ClientComponent: React.FC = () => {\n const [count, setCount] = useState(0);\n\n useEffect(() => {\n const intv = setInterval(() => {\n setCount((prev) => prev + 1); // update state each 1s\n }, 1000);\n return () => clearInterval(intv);\n }, []);\n\n useEffectOnce(() => {\n console.log(\"Component did mount\");\n return () => {\n console.log(\"Component did unmount\");\n };\n });\n\n return
{count}
;\n};\n```\n\n\n\n---\n\n##### `useUpdateEffect`\n\nModified version of `useEffect` that skips the first render.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | ---------------------- | ----------------------------------------------------------------------- |\n| `effect` | `React.EffectCallback` | Imperative function that can return a cleanup function. |\n| `deps` | `React.DependencyList` | If present, effect will only activate if the values in the list change. |\n\n\n\n---\n\n\n\nUsage\n\n```tsx\n\"use client\";\n\nimport { useEffect, useState } from \"react\";\nimport { useUpdateEffect } from \"@alessiofrittoli/react-hooks\";\n\nexport const ClientComponent: React.FC = () => {\n const [count, setCount] = useState(0);\n\n useEffect(() => {\n const intv = setInterval(() => {\n setCount((prev) => prev + 1);\n }, 1000);\n return () => clearInterval(intv);\n }, []);\n\n useEffect(() => {\n console.log(\"useEffect\", count); // starts from 0\n return () => {\n console.log(\"useEffect - clean up\", count); // starts from 0\n };\n }, [count]);\n\n useUpdateEffect(() => {\n console.log(\"useUpdateEffect\", count); // starts from 1\n return () => {\n console.log(\"useUpdateEffect - clean up\", count); // starts from 1\n };\n }, [count]);\n\n return
{count}
;\n};\n```\n\n\n\n---\n\n##### `useIsClient`\n\nCheck if the React Hook or Component where this hook is executed is running in a browser environmen","readmeFilename":"README.md"}
![\"Latest](\"https://img.shields.io/npm/v/@alessiofrittoli/react-hooks\")
\n \n \n ![\"Test](\"https://coveralls.io/repos/github/alessiofrittoli/react-hooks/badge.svg\"){kind=icon}
\n \n \n ![\"npm](\"https://img.shields.io/npm/dm/@alessiofrittoli/react-hooks.svg\")
\n \n \n ![\"Dependencies](\"https://img.shields.io/librariesio/release/npm/@alessiofrittoli/react-hooks\")
\n \n![\"Fund](\"https://img.shields.io/static/v1?label=Fund%20this%20package&message=%E2%9D%A4&logo=GitHub&color=%23DB61A2\")