@alessiofrittoli/react-hooks 3.3.0-alpha.1 → 3.3.0-alpha.3

package/README.md

@@ -23,23 +23,37 @@
 
 - [Getting started](#getting-started)
 - [ESLint Configuration](#eslint-configuration)
+- [What's Changed](#whats-changed)
 - [API Reference](#api-reference)
   - [Browser API](#browser-api)
     - [`useStorage`](#usestorage)
     - [`useLocalStorage`](#uselocalstorage)
     - [`useSessionStorage`](#usesessionstorage)
-    - [`useMediaQuery`](#usemediaquery)
+    - [`useConnection`](#useconnection)
     - [`useDarkMode`](#usedarkmode)
+    - [`useEventListener`](#useeventlistener)
     - [`useIsPortrait`](#useisportrait)
+    - [`useMediaQuery`](#usemediaquery)
   - [DOM API](#dom-api)
-    - [`useScrollBlock`](#usescrollblock)
     - [`useFocusTrap`](#usefocustrap)
     - [`useInView`](#useinview)
+    - [`useScrollBlock`](#usescrollblock)
   - [Miscellaneous](#miscellaneous)
+    - [`useInput`](#useinput)
+    - [`useDeferCallback`](#usedefercallback)
+    - [`useEffectOnce`](#useeffectonce)
+    - [`useUpdateEffect`](#useupdateeffect)
     - [`useIsClient`](#useisclient)
     - [`useIsFirstRender`](#useisfirstrender)
-    - [`useUpdateEffect`](#useupdateeffect)
     - [`usePagination`](#usepagination)
+    - [`useSelection`](#useselection)
+  - [Timers](#timers)
+    - [`useDebounce`](#usedebounce)
+    - [`useInterval`](#useinterval)
+    - [`useIntervalWhenVisible`](#useintervalwhenvisible)
+    - [`useLightInterval`](#uselightinterval)
+    - [`useTimeout`](#usetimeout)
+    - [`useLightTimeout`](#uselighttimeout)
 - [Development](#development)
   - [Install depenendencies](#install-depenendencies)
   - [Build the source code](#build-the-source-code)
@@ -88,6 +102,15 @@ export default config
 
 ---
 
+### What's Changed
+
+#### Updates in the latest release 🎉
+
+- Add `useDeferCallback`. See [API Reference](#usedefercallback) for more info.
+- Add missing API Referefence sections.
+
+---
+
 ### API Reference
 
 #### Browser API
@@ -259,75 +282,26 @@ Applies the same API Reference.
 
 ---
 
-##### `useMediaQuery`
-
-Get Document Media matches and listen for changes.
-
-<details>
-
-<summary style="cursor:pointer">Parameters</summary>
-
-| Parameter | Type     | Default | Description |
-|-----------|----------|---------|-------------|
-| `query`   | `string` | - | A string specifying the media query to parse into a `MediaQueryList`. |
-| `options` | `UseMediaQueryOptions\|UseMediaQueryStateOptions` | - | An object defining custom options. |
-| `options.updateState` | `boolean` | `true` | Indicates whether the hook will dispatch a React state update when the given `query` change event get dispatched. |
-| `options.onChange` | `OnChangeHandler` | - | A custom callback that will be invoked on initial page load and when the given `query` change event get dispatched. |
-| | | | This callback is required if `updateState` is set to `false`. |
-
-</details>
+##### `useConnection`
 
----
+Get states about Internet Connection.
 
 <details>
 
 <summary style="cursor:pointer">Returns</summary>
 
-Type: `boolean|void`
-
-- `true` or `false` if the document currently matches the media query list or not.
-- `void` if `updateState` is set to `false`.
-
-</details>
-
----
-
-<details>
-
-<summary style="cursor:pointer">Usage</summary>
-
-###### Check if user device prefers dark color scheme
-
-```tsx
-import { useMediaQuery } from '@alessiofrittoli/react-hooks'
-
-const isDarkOS = useMediaQuery( '(prefers-color-scheme: dark)' )
-```
-
----
+Type: `UseConnectionReturnType`
 
-###### Listen changes with no state updates
-
-```tsx
-import { useMediaQuery } from '@alessiofrittoli/react-hooks'
+An object with the following properties:
 
-useMediaQuery( '(prefers-color-scheme: dark)', {
-  updateState: false,
-  onChange( matches ) {
-    console.log( 'is dark OS?', matches )
-  }
-} )
-```
+- `connection`: `online | offline` - Indicates the connections status.
+- `isOnline`: `boolean` - Indicates whether the current device is online.
+- `isOffline`: `boolean` - Indicates whether the current device is offline.
 
 </details>
 
 ---
 
-##### `useConnection`
-
-Docs coming soon
-
----
 
 ##### `useDarkMode`
 
@@ -482,20 +456,26 @@ Just make sure to define both `light` and `dark` theme-color tags in your docume
 
 ---
 
-##### `useIsPortrait`
-
-Check if device is portrait oriented.
+##### `useEventListener`
 
-React State get updated when device orientation changes.
+Attach a new Event listener to the `Window`, `Document`, `MediaQueryList` or an `HTMLElement`.
 
 <details>
 
-<summary style="cursor:pointer">Returns</summary>
+<summary style="cursor:pointer">Parameters</summary>
 
-Type: `boolean`
+<details>
 
-- `true` if the device is portrait oriented.
-- `false` otherwise.
+<summary style="cursor:pointer">Window events</summary>
+
+| Parameter | Type     | Description |
+|-----------|----------|-------------|
+| `type`    | `K\|K[]` | The `Window` event name or an array of event names. |
+| `options` | `WindowListenerOptions<K>` | An object defining init options. |
+| `options.listener` | `WindowEventListener<K>` | The Window Event listener. |
+| `options.onLoad` | `() => void` | A custom callback executed before event listener get attached. |
+| `options.onCleanUp` | `() => void` | A custom callback executed after event listener get removed. |
+| `options.options` | `ListenerOptions` | Specifies characteristics about the event listener. See [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options). |
 
 </details>
 
@@ -503,33 +483,53 @@ Type: `boolean`
 
 <details>
 
-<summary style="cursor:pointer">Usage</summary>
-
-###### Check if user device is in landscape
-
-```tsx
-import { useIsPortrait } from '@alessiofrittoli/react-hooks'
+<summary style="cursor:pointer">Document events</summary>
 
-const isLandscape = ! useIsPortrait()
-```
+| Parameter | Type     | Description |
+|-----------|----------|-------------|
+| `type`    | `K\|K[]` | The `Document` event name or an array of event names. |
+| `options` | `DocumentListenerOptions<K>` | An object defining init options. |
+| `options.target` | `Document\|null\|React.RefObject<Document\|null>` | The `Document` reference or a React RefObject of the `Document`. |
+| `options.listener` | `DocumentEventListener<K>` | The Document Event listener. |
+| `options.onLoad` | `() => void` | A custom callback executed before event listener get attached. |
+| `options.onCleanUp` | `() => void` | A custom callback executed after event listener get removed. |
+| `options.options` | `ListenerOptions` | Specifies characteristics about the event listener. See [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options). |
 
 </details>
 
 ---
 
-#### DOM API
+<details>
 
-##### `useScrollBlock`
+<summary style="cursor:pointer">HTMLElement events</summary>
 
-Prevent Element overflow.
+| Parameter | Type     | Description |
+|-----------|----------|-------------|
+| `type`    | `K\|K[]` | The `HTMLElement` event name or an array of event names. |
+| `options` | `ElementListenerOptions<K>` | An object defining init options. |
+| `options.target` | `T\|React.RefObject<T\| null>` | The React RefObject of the target where the listener get attached to. |
+| `options.listener` | `ElementEventListener<K>` | The HTMLElement Event listener. |
+| `options.onLoad` | `() => void` | A custom callback executed before event listener get attached. |
+| `options.onCleanUp` | `() => void` | A custom callback executed after event listener get removed. |
+| `options.options` | `ListenerOptions` | Specifies characteristics about the event listener. See [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options). |
+
+</details>
+
+---
 
 <details>
 
-<summary style="cursor:pointer">Parameters</summary>
+<summary style="cursor:pointer">MediaQuery events</summary>
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `target`  | `React.RefObject<HTMLElement\|null>` | `Document.documentElement` | (Optional) The React RefObject target HTMLElement. |
+| Parameter | Type     | Description |
+|-----------|----------|-------------|
+| `type`    | `change` | The `MediaQueryList` event name. |
+| `options` | `MediaQueryListenerOptions` | An object defining init options. |
+| `options.query` | `string` | The Media Query string to check. |
+| `options.listener` | `MediaQueryChangeListener` | The MediaQueryList Event listener. |
+| `options.onLoad` | `() => void` | A custom callback executed before event listener get attached. |
+| `options.onCleanUp` | `() => void` | A custom callback executed after event listener get removed. |
+| `options.options` | `ListenerOptions` | Specifies characteristics about the event listener. See [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options). |
 
 </details>
 
@@ -537,11 +537,19 @@ Prevent Element overflow.
 
 <details>
 
-<summary style="cursor:pointer">Returns</summary>
+<summary style="cursor:pointer">Custom events</summary>
 
-Type: `[ () => void, () => void ]`
+| Parameter | Type     | Description |
+|-----------|----------|-------------|
+| `type`    | `K\|K[]` | The custom event name or an array of event names. |
+| `options` | `CustomEventListenerOptions<T, K>` | An object defining init options. |
+| `options.target` | `Document\|HTMLElement\|null\|React.RefObject<Document\|HTMLElement\|null>` | (Optional) The target where the listener get attached to. If not set, the listener will get attached to the `Window` object. |
+| `options.listener` | `( event: T[ K ] ) => void` | The Event listener. |
+| `options.onLoad` | `() => void` | A custom callback executed before event listener get attached. |
+| `options.onCleanUp` | `() => void` | A custom callback executed after event listener get removed. |
+| `options.options` | `ListenerOptions` | Specifies characteristics about the event listener. See [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options). |
 
-A tuple with block and restore scroll callbacks.
+</details>
 
 </details>
 
@@ -551,154 +559,354 @@ A tuple with block and restore scroll callbacks.
 
 <summary style="cursor:pointer">Usage</summary>
 
-###### Block Document Overflow
+###### Attach listeners to the Window object
 
 ```tsx
-import { useScrollBlock } from '@alessiofrittoli/react-hooks'
+'use client'
 
-const [ blockScroll, restoreScroll ] = useScrollBlock()
+import { useCallback } from 'react'
+import { useEventListener } from '@alessiofrittoli/react-hooks'
 
-const openPopUpHandler = useCallback( () => {
-  ...
-  blockScroll()
-}, [ blockScroll ] )
+export const MyComponent: React.FC = () => {
 
-const closePopUpHandler = useCallback( () => {
-  ...
-  restoreScroll()
-}, [ restoreScroll ] )
+  useEventListener( 'popstate', {
+    listener: useCallback( event => {
+      ...
+    }, [] ),
+  } )
 
-...
+}
 ```
 
 ---
 
-###### Block HTML Element Overflow
+###### Attach listeners to the Document object
 
 ```tsx
-const elementRef = useRef<HTMLDivElement>( null )
+'use client'
 
-const [ blockScroll, restoreScroll ] = useScrollBlock( elementRef )
+import { useCallback } from 'react'
+import { useEventListener } from '@alessiofrittoli/react-hooks'
 
-const scrollBlockHandler = useCallback( () => {
-  ...
-  blockScroll()
-}, [ blockScroll ] )
+export const MyComponent: React.FC = () => {
 
-const scrollRestoreHandler = useCallback( () => {
-  ...
-  restoreScroll()
-}, [ restoreScroll ] )
+  useEventListener( 'click', {
+    target    : typeof document !== 'undefined' ? document : null,
+    listener  : useCallback( event => {
+      ...
+    }, [] ),
+  } )
 
-...
+}
 ```
 
-</details>
-
 ---
 
-##### `useFocusTrap`
+###### Attach listeners to an HTMLElement
 
-Trap focus inside the given HTML Element.
+```tsx
+'use client'
 
-This comes pretty handy when rendering a modal that shouldn't be closed without a user required action.
+import { useCallback, useRef } from 'react'
+import { useEventListener } from '@alessiofrittoli/react-hooks'
 
-<details>
+export const MyComponent: React.FC = () => {
 
-<summary style="cursor:pointer">Parameters</summary>
+  const buttonRef = useRef<HTMLButtonElement>( null )
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `target`  | `React.RefObject<HTMLElement\|null>` | The target HTMLElement React RefObject to trap focus within. |
-|           |      | If no target is given, you must provide the target HTMLElement when calling `setFocusTrap`. |
+  useEventListener( 'click', {
+    target: buttonRef,
+    listener: useCallback( event => {
+      ...
+    }, [] ),
+  } )
 
-</details>
+  return (
+    <button ref={ buttonRef }>Button</button>
+  )
+
+}
+```
 
 ---
 
-<details>
+###### Attach listeners to a MediaQueryList
 
-<summary style="cursor:pointer">Returns</summary>
+```tsx
+import { useCallback } from 'react'
+import { useEventListener } from '@alessiofrittoli/react-hooks'
 
-Type: `readonly [ SetFocusTrap, RestoreFocusTrap ]`
+export const MyComponent: React.FC = () => {
 
-A tuple containing:
+  useEventListener( 'change', {
+    query     : '(max-width: 768px)',
+    listener  : useCallback( event => {
+      if ( event.matches ) {
+        ...
+      }
+    }, [] )
+  } )
 
-- `setFocusTrap`: A function to enable the focus trap. Optionally accept an HTMLElement as target.
-- `restoreFocusTrap`: A function to restore the previous focus state.
+}
+```
+
+---
+
+###### Listen dispatched custom events
+
+```tsx
+import { useCallback } from 'react'
+import { useEventListener } from '@alessiofrittoli/react-hooks'
+
+class CustomEvent extends Event
+{
+  isCustom: boolean
+
+  constructor( type: string, eventInitDict?: EventInit )
+  {
+    super( type, eventInitDict )
+    this.isCustom = true
+  }
+}
+
+
+type CustomEventMap = {
+  customEventName: CustomEvent
+}
+
+
+export const MyComponent: React.FC = () => {
+
+  const clickHandler = useCallback( () => {
+    document.dispatchEvent( new CustomEvent( 'customEventName' ) )
+  }, [] )
+
+  useEventListener<CustomEventMap>( 'customEventName', {
+    target    : typeof document !== 'undefined' ? document : null,
+    listener  : useCallback( event => {
+      if ( event.isCustom ) {
+        ...
+      }
+    }, [] )
+  } )
+
+
+  return (
+    <button onClick={ clickHandler }>Click me to dispatch custom event</button>
+  )
+
+}
+```
+
+---
 
 </details>
 
 ---
 
-<details>
+##### `useIsPortrait`
 
-<summary style="cursor:pointer">Usage</summary>
+Check if device is portrait oriented.
 
-###### Defining the target on hook initialization
+React State get updated when device orientation changes.
 
-```tsx
-import { useFocusTrap } from '@alessiofrittoli/react-hooks'
+<details>
 
-const modalRef = useRef<HTMLDivElement>( null )
-const [ setFocusTrap, restoreFocusTrap ] = useFocusTrap( modalRef )
+<summary style="cursor:pointer">Returns</summary>
 
-const modalOpenHandler = useCallback( () => {
-  if ( ! modalRef.current ) return
-  // ... open modal
-  setFocusTrap()
-  modalRef.current.focus() // focus the dialog so next tab will focus the next element inside the modal
-}, [ setFocusTrap ] )
+Type: `boolean`
 
-const modalCloseHandler = useCallback( () => {
-  // ... close modal
-  restoreFocusTrap() // cancel focus trap and restore focus to the last active element before enablig the focus trap
-}, [ restoreFocusTrap ] )
-```
+- `true` if the device is portrait oriented.
+- `false` otherwise.
+
+</details>
 
 ---
 
-###### Defining the target ondemand
+<details>
 
-```tsx
-import { useFocusTrap } from '@alessiofrittoli/react-hooks'
+<summary style="cursor:pointer">Usage</summary>
 
-const modalRef = useRef<HTMLDivElement>( null )
-const modal2Ref = useRef<HTMLDivElement>( null )
-const [ setFocusTrap, restoreFocusTrap ] = useFocusTrap()
+###### Check if user device is in landscape
 
-const modalOpenHandler = useCallback( () => {
-  if ( ! modalRef.current ) return
-  // ... open modal
-  setFocusTrap( modalRef.current )
-  modalRef.current.focus()
-}, [ setFocusTrap ] )
+```tsx
+import { useIsPortrait } from '@alessiofrittoli/react-hooks'
 
-const modal2OpenHandler = useCallback( () => {
-  if ( ! modal2Ref.current ) return
-  // ... open modal
-  setFocusTrap( modal2Ref.current )
-  modal2Ref.current.focus()
-}, [ setFocusTrap ] )
+const isLandscape = ! useIsPortrait()
 ```
 
 </details>
 
 ---
 
-##### `useInView`
+##### `useMediaQuery`
 
-Check if the given target Element is intersecting with an ancestor Element or with a top-level document's viewport.
+Get Document Media matches and listen for changes.
 
 <details>
 
 <summary style="cursor:pointer">Parameters</summary>
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `target`  | `React.RefObject<Element\|null>` | The React.RefObject of the target Element to observe. |
-| `options` | `UseInViewOptions` | (Optional) An object defining custom `IntersectionObserver` options. |
-| `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. |
+| Parameter | Type     | Default | Description |
+|-----------|----------|---------|-------------|
+| `query`   | `string` | - | A string specifying the media query to parse into a `MediaQueryList`. |
+| `options` | `UseMediaQueryOptions\|UseMediaQueryStateOptions` | - | An object defining custom options. |
+| `options.updateState` | `boolean` | `true` | Indicates whether the hook will dispatch a React state update when the given `query` change event get dispatched. |
+| `options.onChange` | `OnChangeHandler` | - | A custom callback that will be invoked on initial page load and when the given `query` change event get dispatched. |
+| | | | This callback is required if `updateState` is set to `false`. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Returns</summary>
+
+Type: `boolean|void`
+
+- `true` or `false` if the document currently matches the media query list or not.
+- `void` if `updateState` is set to `false`.
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Usage</summary>
+
+###### Check if user device prefers dark color scheme
+
+```tsx
+import { useMediaQuery } from '@alessiofrittoli/react-hooks'
+
+const isDarkOS = useMediaQuery( '(prefers-color-scheme: dark)' )
+```
+
+---
+
+###### Listen changes with no state updates
+
+```tsx
+import { useMediaQuery } from '@alessiofrittoli/react-hooks'
+
+useMediaQuery( '(prefers-color-scheme: dark)', {
+  updateState: false,
+  onChange( matches ) {
+    console.log( 'is dark OS?', matches )
+  }
+} )
+```
+
+</details>
+
+---
+
+#### DOM API
+
+##### `useFocusTrap`
+
+Trap focus inside the given HTML Element.
+
+This comes pretty handy when rendering a modal that shouldn't be closed without a user required action.
+
+<details>
+
+<summary style="cursor:pointer">Parameters</summary>
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `target`  | `React.RefObject<HTMLElement\|null>` | The target HTMLElement React RefObject to trap focus within. |
+|           |      | If no target is given, you must provide the target HTMLElement when calling `setFocusTrap`. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Returns</summary>
+
+Type: `readonly [ SetFocusTrap, RestoreFocusTrap ]`
+
+A tuple containing:
+
+- `setFocusTrap`: A function to enable the focus trap. Optionally accept an HTMLElement as target.
+- `restoreFocusTrap`: A function to restore the previous focus state.
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Usage</summary>
+
+###### Defining the target on hook initialization
+
+```tsx
+import { useFocusTrap } from '@alessiofrittoli/react-hooks'
+
+const modalRef = useRef<HTMLDivElement>( null )
+const [ setFocusTrap, restoreFocusTrap ] = useFocusTrap( modalRef )
+
+const modalOpenHandler = useCallback( () => {
+  if ( ! modalRef.current ) return
+  // ... open modal
+  setFocusTrap()
+  modalRef.current.focus() // focus the dialog so next tab will focus the next element inside the modal
+}, [ setFocusTrap ] )
+
+const modalCloseHandler = useCallback( () => {
+  // ... close modal
+  restoreFocusTrap() // cancel focus trap and restore focus to the last active element before enablig the focus trap
+}, [ restoreFocusTrap ] )
+```
+
+---
+
+###### Defining the target ondemand
+
+```tsx
+import { useFocusTrap } from '@alessiofrittoli/react-hooks'
+
+const modalRef = useRef<HTMLDivElement>( null )
+const modal2Ref = useRef<HTMLDivElement>( null )
+const [ setFocusTrap, restoreFocusTrap ] = useFocusTrap()
+
+const modalOpenHandler = useCallback( () => {
+  if ( ! modalRef.current ) return
+  // ... open modal
+  setFocusTrap( modalRef.current )
+  modalRef.current.focus()
+}, [ setFocusTrap ] )
+
+const modal2OpenHandler = useCallback( () => {
+  if ( ! modal2Ref.current ) return
+  // ... open modal
+  setFocusTrap( modal2Ref.current )
+  modal2Ref.current.focus()
+}, [ setFocusTrap ] )
+```
+
+</details>
+
+---
+
+##### `useInView`
+
+Check if the given target Element is intersecting with an ancestor Element or with a top-level document's viewport.
+
+<details>
+
+<summary style="cursor:pointer">Parameters</summary>
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `target`  | `React.RefObject<Element\|null>` | The React.RefObject of the target Element to observe. |
+| `options` | `UseInViewOptions` | (Optional) An object defining custom `IntersectionObserver` options. |
+| `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. |
 | `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. |
 | `options.amount` | `'all'\|'some'\|number\|number[]` | (Optional) The intersecting target thresholds. |
 | | | Threshold can be set to: |
@@ -946,36 +1154,29 @@ const AsyncStartExample: React.FC = () => {
 
 ---
 
-#### Miscellaneous
-
----
+##### `useScrollBlock`
 
-##### `useInput`
+Prevent Element overflow.
 
-Docs coming soon
+<details>
 
----
+<summary style="cursor:pointer">Parameters</summary>
 
-##### `useEffectOnce`
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `target`  | `React.RefObject<HTMLElement\|null>` | `Document.documentElement` | (Optional) The React RefObject target HTMLElement. |
 
-Docs coming soon
+</details>
 
 ---
 
-##### `useIsClient`
-
-Check if the React Hook or Component where this hook is executed is running in a browser environment.
-
-This is pretty usefull to avoid hydration errors.
-
 <details>
 
 <summary style="cursor:pointer">Returns</summary>
 
-Type: `boolean`
+Type: `[ () => void, () => void ]`
 
-- `true` if the React Hook or Component is running in a browser environment.
-- `false` otherwise.
+A tuple with block and restore scroll callbacks.
 
 </details>
 
@@ -985,42 +1186,109 @@ Type: `boolean`
 
 <summary style="cursor:pointer">Usage</summary>
 
-###### Basic usage
+###### Block Document Overflow
 
 ```tsx
-'use client'
+import { useScrollBlock } from '@alessiofrittoli/react-hooks'
 
-import { useIsClient } from '@alessiofrittoli/react-hooks'
+const [ blockScroll, restoreScroll ] = useScrollBlock()
 
-export const ClientComponent: React.FC = () => {
+const openPopUpHandler = useCallback( () => {
+  ...
+  blockScroll()
+}, [ blockScroll ] )
 
-  const isClient = useIsClient()
+const closePopUpHandler = useCallback( () => {
+  ...
+  restoreScroll()
+}, [ restoreScroll ] )
 
-  return (
-    <div>Running { ! isClient ? 'server' : 'client' }-side</div>
-  )
+...
+```
 
-}
+---
+
+###### Block HTML Element Overflow
+
+```tsx
+const elementRef = useRef<HTMLDivElement>( null )
+
+const [ blockScroll, restoreScroll ] = useScrollBlock( elementRef )
+
+const scrollBlockHandler = useCallback( () => {
+  ...
+  blockScroll()
+}, [ blockScroll ] )
+
+const scrollRestoreHandler = useCallback( () => {
+  ...
+  restoreScroll()
+}, [ restoreScroll ] )
+
+...
 ```
 
 </details>
 
 ---
 
-##### `useIsFirstRender`
+#### Miscellaneous
 
-Check if is first React Hook/Component render.
+##### `useInput`
+
+Handle input states with ease.
+
+<details>
+
+<summary style="cursor:pointer">Type Parameters</summary>
+
+| Parameter | Description            |
+|-----------|------------------------|
+| `I`       | The input value type.  |
+| `O`       | The output value type. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Parameters</summary>
+
+| Parameter | Type     | Default | Description                 |
+|-----------|----------|---------|-----------------------------|
+| `options` | `UseInputOptions<I, O>` | `{}` | An object defining custom options. |
+| `options.inputRef` | `React.RefObject<InputType>` | - | (Optional) The React HTML input element ref. |
+| `options.initialValue` | `O\|null` | - | (Optional) The input initial value. |
+| `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. |
+| `options.validate` | `ValidateValueHandler<O>` | - | (Optional) Value validation handler. If `parse` callback is given, the `value` will be parsed before validation. |
+| `options.parse` | `ParseValueHandler<I, O>` | - | (Optional) Parse value. |
+| `options.onChange` | `ChangeHandler<O>` | - | (Optional) A callable function executed when the `ChangeEvent` is dispatched on the HTML input element. |
+
+</details>
+
+---
 
 <details>
 
 <summary style="cursor:pointer">Returns</summary>
 
-Type: `boolean`
+Type: `UseInputOutput<I, O>`
 
-- `true` at the mount time.
-- `false` otherwise.
+An object containing the following properties:
 
-Note that if the React Hook/Component has no state updates, `useIsFirstRender` will always return `true`.
+| Property        | Type | Description |
+|-----------------|------|-------------|
+| `isEmpty`       | `boolean` | Indicates whether the Input is empty or not. |
+| `hasError`      | `boolean` | Indicates whether the input has error or not. |
+| | | It will return true if the Input does not pass the validation checks and it has been touched. |
+| | | Please refer to the `isValid` property to check the Input validity regardless of whether it has been touched or not. |
+| `changeHandler` | `React.ChangeEventHandler<InputType>` | Change handler callback used to handle Input change events. |
+| `blurHandler`   | `() => void` | Blur handler callback used to handle Input blur events. |
+| `setValue`      | `( value: O ) => void` | Call `setValue` method to update input value. |
+| `submit`        | `() => void` | Call `submit` method to re-run validations and ensure error state is updated successfully. |
+| `reset`         | `() => void` | Call `reset` method to reset the Input state. |
+| `focus`         | `() => void` | Call `focus` method to focus the Input Element. `inputRef` must be provided in the input options. |
 
 </details>
 
@@ -1033,28 +1301,216 @@ Note that if the React Hook/Component has no state updates, `useIsFirstRender` w
 ###### Basic usage
 
 ```tsx
-'use client'
+const MyComponent: React.FC = () => {
 
-import { useIsFirstRender } from '@alessiofrittoli/react-hooks'
+  const input = useInput<string>()
 
-export const ClientComponent: React.FC = () => {
+  return (
+    <input
+      type='text'
+      value={ input.value || '' }
+      onChange={ input.changeHandler }
+      onBlur={ input.blurHandler }
+    />
+  )
 
-  const isFirstRender = useIsFirstRender()
-  const [ counter, setCounter ] = useState( 0 )
+}
+```
+
+---
+
+###### Displaying custom error messages
+
+```tsx
+import { useInput, type ValidateValueHandler } from '@alessiofrittoli/react-hooks'
+
+const isNotEmpty: ValidateValueHandler<string> = value => (
+  ! value ? false : value.trim().length > 0
+)
+
+const MyComponent: React.FC = () => {
+
+  const input = useInput<string>( {
+    validate: isNotEmpty,
+  } )
+
+  return (
+    <>
+      <input
+        value={ input.value || '' }
+        onChange={ input.changeHandler }
+        onBlur={ input.blurHandler }
+      />
+      { input.hasError && (
+        <span>The input cannot be empty.</span>
+      ) }
+    </>
+  )
+
+}
+```
+
+---
+
+###### Parsing and validating parsed value
+
+```tsx
+import { formatDate, isValidDate } from '@alessiofrittoli/date-utils'
+import { useInput, type ValidateValueHandler, type ParseValueHandler } from '@alessiofrittoli/react-hooks'
+
+const parseStringToDate: ParseValueHandler<string, Date> = value => (
+  value ? new Date( value ) : undefined
+)
+
+
+const validateInputDate: ValidateValueHandler<Date> = value => (
+  isValidDate( value ) && value.getTime() > Date.now()
+)
+
+
+const MyComponent: React.FC = () => {
+
+  const input = useInput<string, Date>( {
+    parse     : parseStringToDate,
+    validate  : validateInputDate,
+  } )
+  
+
+  return (
+    <>
+      <input
+        type='datetime-local'
+        value={ input.value ? formatDate( input.value, 'Y-m-dTH:i' ) : '' }
+        onChange={ input.changeHandler }
+        onBlur={ input.blurHandler }
+      />
+      { input.hasError && (
+        <span>Please choose a date no earlier than today</span>
+      ) }
+    </>
+  )
+
+}
+```
+
+</details>
+
+---
+
+##### `useDeferCallback`
+
+`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.
+
+Since [`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.
+To avoid these pitfalls you can memoize and defer your task with `useDeferCallback`.
+
+Take a look at [`deferTask`](https://npmjs.com/package/@alessiofrittoli/web-utils?activeTab=readme#deferTask) to defer single tasks in a function handler.
+
+<details>
+
+<summary style="cursor:pointer">Type Parameters</summary>
+
+| Parameter | Description                  |
+|-----------|------------------------------|
+| `T`       | The task function definition. `unknown` types will be inherited by your function type definition. |
+| `U`       | The task function arguments. `unknown` types will be inherited by your function type. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Parameters</summary>
+
+| Parameter | Type     | Description                 |
+|-----------|----------|-----------------------------|
+| `task`    | `T`      | The task callable function. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Returns</summary>
+
+Type: `( ...args: U ) => Promise<Awaited<ReturnType<T>>>`
+
+A new memoized handler which returns a new Promise that returns the `task` result once fulfilled.
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Usage</summary>
+
+```tsx
+const MyComponent: React.FC = () => {
+
+  const clickHandler = useDeferCallback<React.MouseEventHandler>(
+    event => { ... }, []
+  )
+
+  return (
+    <button onClick={ clickHandler }>Button</button>
+  )
+
+}
+```
+
+</details>
+
+---
+
+##### `useEffectOnce`
+
+Modified version of `useEffect` that only run once on intial load.
+
+<details>
+
+<summary style="cursor:pointer">Parameters</summary>
+
+| Parameter | Type                   | Description |
+|-----------|------------------------|-------------|
+| `effect`  | `React.EffectCallback` | Imperative function that can return a cleanup function. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Usage</summary>
+
+```tsx
+'use client'
+
+import { useEffect, useState } from 'react'
+import { useEffectOnce } from '@alessiofrittoli/react-hooks'
+
+export const ClientComponent: React.FC = () => {
+
+  const [ count, setCount ] = useState( 0 )
 
   useEffect( () => {
     const intv = setInterval( () => {
-      setCounter( prev => prev + 1 )
+      setCount( prev => prev + 1 ) // update state each 1s
     }, 1000 )
     return () => clearInterval( intv )
   }, [] )
 
+  useEffectOnce( () => {
+    console.log( 'Component did mount' )
+    return () => {
+      console.log( 'Component did unmount' )
+    }
+  } )
+
   return (
-    <div>
-      { isFirstRender ? 'First render' : 'Subsequent render' }
-      <hr />
-      { counter }
-    </div>
+    <div>{ count }</div>
   )
 
 }
@@ -1085,8 +1541,6 @@ Modified version of `useEffect` that skips the first render.
 
 <summary style="cursor:pointer">Usage</summary>
 
-###### Basic usage
-
 ```tsx
 'use client'
 
@@ -1129,6 +1583,104 @@ export const ClientComponent: React.FC = () => {
 
 ---
 
+##### `useIsClient`
+
+Check if the React Hook or Component where this hook is executed is running in a browser environment.
+
+This is pretty usefull to avoid hydration errors.
+
+<details>
+
+<summary style="cursor:pointer">Returns</summary>
+
+Type: `boolean`
+
+- `true` if the React Hook or Component is running in a browser environment.
+- `false` otherwise.
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Usage</summary>
+
+```tsx
+'use client'
+
+import { useIsClient } from '@alessiofrittoli/react-hooks'
+
+export const ClientComponent: React.FC = () => {
+
+  const isClient = useIsClient()
+
+  return (
+    <div>Running { ! isClient ? 'server' : 'client' }-side</div>
+  )
+
+}
+```
+
+</details>
+
+---
+
+##### `useIsFirstRender`
+
+Check if is first React Hook/Component render.
+
+<details>
+
+<summary style="cursor:pointer">Returns</summary>
+
+Type: `boolean`
+
+- `true` at the mount time.
+- `false` otherwise.
+
+Note that if the React Hook/Component has no state updates, `useIsFirstRender` will always return `true`.
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Usage</summary>
+
+```tsx
+'use client'
+
+import { useIsFirstRender } from '@alessiofrittoli/react-hooks'
+
+export const ClientComponent: React.FC = () => {
+
+  const isFirstRender = useIsFirstRender()
+  const [ counter, setCounter ] = useState( 0 )
+
+  useEffect( () => {
+    const intv = setInterval( () => {
+      setCounter( prev => prev + 1 )
+    }, 1000 )
+    return () => clearInterval( intv )
+  }, [] )
+
+  return (
+    <div>
+      { isFirstRender ? 'First render' : 'Subsequent render' }
+      <hr />
+      { counter }
+    </div>
+  )
+
+}
+```
+
+</details>
+
+---
+
 ##### `usePagination`
 
 Get pagination informations based on the given options.
@@ -1141,7 +1693,597 @@ See [`paginate`](https://github.com/alessiofrittoli/math-utils/blob/master/docs/
 
 ##### `useSelection`
 
-Docs coming soon
+A React hook for managing selection states in an array.
+
+Provides functionality for single and group selection, as well as resetting the selection.
+
+<details>
+
+<summary style="cursor:pointer">Type Parameters</summary>
+
+| Parameter | Description                  |
+|-----------|------------------------------|
+| `V`       | The type of the values in the `array`. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Parameters</summary>
+
+| Parameter | Type  | Default | Description                  |
+|-----------|-------|---------|-----------------------------|
+| `array`   | `V[]` | -      | The array of items to manage selection for. |
+| `initial` | `V[]` | []     | The initial selection state. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Returns</summary>
+
+An object containing the selection state and handlers.
+
+- `selection`: `V[]` - The current selected items.
+- `hasSelection`: `boolean` - Indicates whether `selection` is not empty. Short-hand for `selection.length > 0`.
+- `isSelected`: `IsSelectedHandler<V>` - Check if the given `entry` is in the selection.
+- `setSelection`: `SetSelectionHandler<V>` - A React Dispatch SetStateAction that allows custom selection update.
+- `select`: `SelectHandler<V>` - Update selection by adding a new `entry` or removing the given `entry` if already exists in the selection.
+- `groupSelect`: `GroupSelectHandler<V>` - Select all items from the given `array` starting from the first item in the selection up to the given `entry`.
+- `selectAll`: `SelectAllHandler` - Add all entries from the given `array` to the selection.
+- `resetSelection`: `ResetSelectionHandler` - Removes all entries from the selection.
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Usage</summary>
+
+```tsx
+'use client'
+
+import { useCallback, useMemo } from 'react'
+import { useSelection } from '@alessiofrittoli/react-hooks'
+
+interface Item
+{
+  id    : number
+  name  : string
+}
+
+const items: Item[] = [
+  {
+    id    : 1,
+    name  : 'item-1',
+  },
+  {
+    id    : 2,
+    name  : 'item-2',
+  },
+  {
+    id    : 3,
+    name  : 'item-3',
+  },
+  {
+    id    : 4,
+    name  : 'item-4',
+  },
+  {
+    id    : 5,
+    name  : 'item-5',
+  },
+]
+
+
+const MyComponent: React.FC = () => {
+
+  const {
+    setSelection, select, groupSelect, isSelected
+  } = useSelection( useMemo( () => items.map( item => item.id ), [] ) )
+
+  const clickHandler = useCallback( ( id: Item[ 'id' ] ) => (
+    ( event: React.MouseEvent<HTMLButtonElement> ) => {
+      if ( event.shiftKey ) {
+        return groupSelect( id ) // group select
+      }
+      if ( event.metaKey || event.ctrlKey ) {
+        return select( id ) // toggle single item in selection
+      }
+      setSelection( prev => (
+        prev.includes( id ) ? [] : [ id ] // toggle single item selection
+      ) )
+    }
+  ), [ select, groupSelect, setSelection ] )
+
+  return (
+    <ul>
+      { items.map( item => (
+        <li key={ item.id }>
+          <button
+            onClick={ clickHandler( item.id ) }
+            style={ {
+              border: isSelected( item.id ) ? '1px solid red' : ' 1px solid black'
+            } }
+          >{ item.name }</button>
+        </li>
+      ) ) }
+    </ul>
+  )
+
+}
+```
+
+</details>
+
+---
+
+#### Timers
+
+#### `useDebounce`
+
+Debounce a value by a specified delay.
+
+This hook returns a debounced version of the input value, which only updates
+after the specified delay has passed without any changes to the input value.
+
+It is useful for scenarios like search input fields or other cases where
+frequent updates should be minimized.
+
+The `Timeout` automatically restarts when the given `value` changes.
+
+<details>
+
+<summary style="cursor:pointer">Type Parameters</summary>
+
+| Parameter | Description              |
+|-----------|--------------------------|
+| `T`       | The type of the `value`. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Parameters</summary>
+
+| Parameter | Type     | Default | Description                 |
+|-----------|----------|---------|-----------------------------|
+| `value`   | `T`      | -       | The value to debounce. This can be of any type. |
+| `delay`   | `number` | 500     | The debounce delay in milliseconds. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Returns</summary>
+
+Type: `T`
+
+The debounced value, which updates only after the delay has passed.
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Usage</summary>
+
+```tsx
+'use client'
+
+import { useEffect, useState } from 'react'
+import { useDebounce } from '@alessiofrittoli/react-hooks'
+
+const MyComponent: React.FC = () => {
+
+  const [ query, setQuery ] = useState( '' )
+  const debouncedQuery = useDebounce( query )
+
+  useEffect( () => {
+    if ( ! debouncedQuery ) return
+
+    fetch( '...', {
+      // ...
+      body: JSON.stringify( { query: debouncedQuery } )
+    } )
+
+  }, [ debouncedQuery ] )
+
+  return (
+    <input
+      onChange={ event => setQuery( event.target.value ) }
+    />
+  )
+
+}
+```
+
+</details>
+
+---
+
+#### `useInterval`
+
+Schedules repeated execution of `callback` every `delay` milliseconds.
+
+When `delay` is larger than `2147483647` or less than `1` or `NaN`, the `delay` will be set to `1`. Non-integer delays are truncated to an integer.
+If `callback` is not a function, a `TypeError` will be thrown.
+
+The `Timeout` is automatically cancelled on unmount.
+
+<details>
+
+<summary style="cursor:pointer">Type Parameters</summary>
+
+| Parameter | Description              |
+|-----------|--------------------------|
+| `T`       | An Array defining optional arguments passed to the `callback`. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Parameters</summary>
+
+| Parameter | Type     | Default | Description                 |
+|-----------|----------|---------|-----------------------------|
+| `callback`| `TimerHandler<T>` | - | The function to call when the timer elapses. |
+| `options` | `TimerOptions<T>` | - | (Optional) An object defining custom timer options. |
+| `options.delay` | `number` | `1` | The number of milliseconds to wait before calling the `callback`. |
+| `options.args` | `T` | - | Optional arguments to pass when the `callback` is called. |
+| `options.autoplay` | `boolean` | `true` | Indicates whether auto start the timer. |
+| `options.updateState` | `boolean` | `false` | Whether to update React state about Timer running status. |
+| `options.runOnStart` | `boolean` | `false` | Indicates whether to execute the callback when timer starts. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Returns</summary>
+
+Type: `TimerReturnType | StateTimerReturnType`
+
+An object with timer utilities.
+
+- start: `StartTimer` - Manually start the timer.
+- stop: `StopTimer` - Manually stop the timer.
+
+If `updateState` is set to `true` then the following property is added in the returned object.
+
+- isActive: `boolean` - Indicates whether the timer is active.
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Usage</summary>
+
+##### Basic usage
+
+```tsx
+'use client'
+
+import { useCallback } from 'react'
+import { useInterval } from '@alessiofrittoli/react-hooks'
+
+const MyComponent: React.FC = () => {
+
+  const { stop } = useInterval( useCallback( () => {
+    console.log( 'tick timer' )
+  }, [] ), { delay: 1000 } )
+
+  return (
+    <button onClick={ stop }>Stop timer</button>
+  )
+
+}
+```
+
+---
+
+##### Rely on state updates
+
+```tsx
+'use client'
+
+import { useCallback } from 'react'
+import { useInterval } from '@alessiofrittoli/react-hooks'
+
+const MyComponent: React.FC = () => {
+
+  const { isActive, start, stop } = useInterval( useCallback( () => {
+    console.log( 'tick timer' )
+  }, [] ), {
+    delay       : 1000,
+    autoplay    : false,
+    runOnStart  : true,
+    updateState : true,
+  } )
+
+  return (
+    <>
+      { ! isActive && (
+        <button onClick={ start }>Start timer</button>
+      ) }
+      { isActive && (
+        <button onClick={ stop }>Stop timer</button>
+      ) }
+    </>
+  )
+
+}
+```
+
+</details>
+
+---
+
+#### `useIntervalWhenVisible`
+
+Schedules repeated execution of `callback` every `delay` milliseconds when `Document` is visible.
+
+This hook automatically starts and stops the interval based on the `Document` visibility.
+
+This hook has the same API of [`useInterval`](#useinterval) and automatically starts and stops timers based on `Document` visibility.
+Refer to [`useInterval`](#useinterval) API Reference for more info.
+
+---
+
+#### `useLightInterval`
+
+Schedules repeated execution of `callback` every `delay` milliseconds.
+
+This is a lighter version of [`useInterval`](#useinterval) and is suggested to use when a basic functionality is enough (no manual start/stop or state updates).
+
+<details>
+
+<summary style="cursor:pointer">Type Parameters</summary>
+
+| Parameter | Description              |
+|-----------|--------------------------|
+| `T`       | An Array defining optional arguments passed to the `callback`. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Parameters</summary>
+
+| Parameter | Type     | Default | Description                 |
+|-----------|----------|---------|-----------------------------|
+| `callback`| `TimerHandler<T>` | - | The function to call when the timer elapses. |
+| `options` | `BasicTimerOptions<T>` | - | (Optional) An object defining custom timer options. |
+| `options.delay` | `number` | `1` | The number of milliseconds to wait before calling the `callback`. |
+| `options.args` | `T` | - | Optional arguments to pass when the `callback` is called. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Usage</summary>
+
+```tsx
+'use client'
+
+import { useCallback } from 'react'
+import { useLightInterval } from '@alessiofrittoli/react-hooks'
+
+const MyComponent: React.FC = () => {
+
+  useLightInterval( useCallback( () => {
+    console.log( 'tick timer' )
+  }, [] ), { delay: 1000 } )
+
+}
+```
+
+</details>
+
+---
+
+#### `useTimeout`
+
+Schedules execution of a one-time `callback` after `delay` milliseconds.
+
+The `callback` will likely not be invoked in precisely `delay` milliseconds.
+
+Node.js makes no guarantees about the exact timing of when callbacks will fire,
+nor of their ordering. The callback will be called as close as possible to the
+time specified.
+
+When `delay` is larger than `2147483647` or less than `1` or `NaN`, the `delay`
+will be set to `1`. Non-integer delays are truncated to an integer.
+
+If `callback` is not a function, a `TypeError` will be thrown.
+
+The `Timeout` is automatically cancelled on unmount.
+
+<details>
+
+<summary style="cursor:pointer">Type Parameters</summary>
+
+| Parameter | Description              |
+|-----------|--------------------------|
+| `T`       | An Array defining optional arguments passed to the `callback`. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Parameters</summary>
+
+| Parameter | Type     | Default | Description                 |
+|-----------|----------|---------|-----------------------------|
+| `callback`| `TimerHandler<T>` | - | The function to call when the timer elapses. |
+| `options` | `TimerOptions<T>` | - | (Optional) An object defining custom timer options. |
+| `options.delay` | `number` | `1` | The number of milliseconds to wait before calling the `callback`. |
+| `options.args` | `T` | - | Optional arguments to pass when the `callback` is called. |
+| `options.autoplay` | `boolean` | `true` | Indicates whether auto start the timer. |
+| `options.updateState` | `boolean` | `false` | Whether to update React state about Timer running status. |
+| `options.runOnStart` | `boolean` | `false` | Indicates whether to execute the callback when timer starts. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Returns</summary>
+
+Type: `TimerReturnType | StateTimerReturnType`
+
+An object with timer utilities.
+
+- start: `StartTimer` - Manually start the timer.
+- stop: `StopTimer` - Manually stop the timer.
+
+If `updateState` is set to `true` then the following property is added in the returned object.
+
+- isActive: `boolean` - Indicates whether the timer is active.
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Usage</summary>
+
+##### Basic usage
+
+```tsx
+'use client'
+
+import { useCallback } from 'react'
+import { useTimeout } from '@alessiofrittoli/react-hooks'
+
+const MyComponent: React.FC = () => {
+
+  const { stop } = useTimeout( useCallback( () => {
+    console.log( 'tick timer' )
+  }, [] ), { delay: 1000 } )
+
+  return (
+    <button onClick={ stop }>Stop timer</button>
+  )
+
+}
+```
+
+---
+
+##### Rely on state updates
+
+```tsx
+'use client'
+
+import { useCallback } from 'react'
+import { useTimeout } from '@alessiofrittoli/react-hooks'
+
+const MyComponent: React.FC = () => {
+
+  const { isActive, start, stop } = useTimeout( useCallback( () => {
+    console.log( 'tick timer' )
+  }, [] ), {
+    delay       : 1000,
+    autoplay    : false,
+    runOnStart  : true,
+    updateState : true,
+  } )
+
+  return (
+    <>
+      { ! isActive && (
+        <button onClick={ start }>Start timer</button>
+      ) }
+      { isActive && (
+        <button onClick={ stop }>Stop timer</button>
+      ) }
+    </>
+  )
+
+}
+```
+
+</details>
+
+---
+
+#### `useLightTimeout`
+
+Schedules execution of a one-time `callback` after `delay` milliseconds.
+
+This is a lighter version of [`useTimeout`](#usetimeout) and is suggested to use when a basic functionality is enough (no manual start/stop or state updates).
+
+<details>
+
+<summary style="cursor:pointer">Type Parameters</summary>
+
+| Parameter | Description              |
+|-----------|--------------------------|
+| `T`       | An Array defining optional arguments passed to the `callback`. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Parameters</summary>
+
+| Parameter | Type     | Default | Description                 |
+|-----------|----------|---------|-----------------------------|
+| `callback`| `TimerHandler<T>` | - | The function to call when the timer elapses. |
+| `options` | `BasicTimerOptions<T>` | - | (Optional) An object defining custom timer options. |
+| `options.delay` | `number` | `1` | The number of milliseconds to wait before calling the `callback`. |
+| `options.args` | `T` | - | Optional arguments to pass when the `callback` is called. |
+
+</details>
+
+---
+
+<details>
+
+<summary style="cursor:pointer">Usage</summary>
+
+```tsx
+'use client'
+
+import { useCallback } from 'react'
+import { useLightTimeout } from '@alessiofrittoli/react-hooks'
+
+const MyComponent: React.FC = () => {
+
+  useLightTimeout( useCallback( () => {
+    console.log( 'tick timer' )
+  }, [] ), { delay: 1000 } )
+
+}
+```
+
+</details>
 
 ---