usehooks-ts

https://usehooks-ts.com/
Admin
usehooks-ts is a lightweight, type-safe collection of React hooks written in TypeScript with...
Tokens:35,415
Snippets:195
Trust Score:8.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Basic Countdown Example

Source: https://usehooks-ts.com/react-hook/use-countdown

Demonstrates how to use the useCountdown hook to create a functional countdown timer with start, stop, and reset buttons, and an input to change the interval.

```jsx
import { useState } from 'react'

import type { ChangeEvent } from 'react'

import { useCountdown } from 'usehooks-ts'

export default function Component() {
  const [intervalValue, setIntervalValue] = useState<number>(1000)
  const [count, { startCountdown, stopCountdown, resetCountdown }] = 
    useCountdown({
      countStart: 60,
      intervalMs: intervalValue,
    })

  const handleChangeIntervalValue = (event: ChangeEvent<HTMLInputElement>) => {
    setIntervalValue(Number(event.target.value))
  }
  return (
    <div>
      <p>Count: {count}</p>

      <input
        type="number"
        value={intervalValue}
        onChange={handleChangeIntervalValue}
      />
      <button onClick={startCountdown}>start</button>
      <button onClick={stopCountdown}>stop</button>
      <button onClick={resetCountdown}>reset</button>
    </div>
  )
}
```

--------------------------------

### Install usehooks-ts with npm

Source: https://usehooks-ts.com/introduction

Install the usehooks-ts library using npm. This command adds the library to your project's dependencies.

```bash
npm install usehooks-ts
```

--------------------------------

### Basic Usage of useWindowSize Hook

Source: https://usehooks-ts.com/react-hook/use-window-size

Import and use the `useWindowSize` hook to get the current window dimensions. Initialize with default values of 0 if width or height are not available.

```javascript
import { useWindowSize } from 'usehooks-ts'

export default function Component() {
  const { width = 0, height = 0 } = useWindowSize()

  return (
    <div>
      The current window dimensions are: {' '}
      <code>{JSON.stringify({ width, height })}</code>
    </div>
  )
}
```

--------------------------------

### Basic Usage of useLocalStorage

Source: https://usehooks-ts.com/react-hook/use-local-storage

Demonstrates how to use the useLocalStorage hook to manage a counter value. It shows how to get the current value, update it using a callback, and reset it by removing the key from localStorage.

```javascript
import { useLocalStorage } from 'usehooks-ts'

export default function Component() {
  const [value, setValue, removeValue] = useLocalStorage('test-key', 0)

  return (
    <div>
      <p>Count: {value}</p>
      <button
        onClick={() => {
          setValue((x: number) => x + 1)
        }}
      >
        Increment
      </button>
      <button
        onClick={() => {
          setValue((x: number) => x - 1)
        }}
      >
        Decrement
      </button>
      <button
        onClick={() => {
          removeValue()
        }}
      >
        Reset
      </button>
    </div>
  )
}
```

--------------------------------

### Usage Example of useEventCallback

Source: https://usehooks-ts.com/react-hook/use-event-callback

Demonstrates how to use the useEventCallback hook to create a memoized click handler. This ensures the handler function reference remains stable across re-renders.

```javascript
import { useEventCallback } from 'usehooks-ts'

export default function Component() {
  const handleClick = useEventCallback(event => {
    // Handle the event here
    console.log('Clicked', event)
  })

  return <button onClick={handleClick}>Click me</button>
}
```

--------------------------------

### Basic Usage of useMediaQuery Hook

Source: https://usehooks-ts.com/react-hook/use-media-query

Import and use the useMediaQuery hook to check if the viewport meets a specific media query condition. This example demonstrates checking for a minimum width of 768px.

```jsx
import { useMediaQuery } from 'usehooks-ts'

export default function Component() {
  const matches = useMediaQuery('(min-width: 768px)')

  return (
    <div>
      {`The view port is ${matches ? 'at least' : 'less than'} 768 pixels wide`}
    </div>
  )
}
```

--------------------------------

### Basic Usage of useToggle

Source: https://usehooks-ts.com/react-hook/use-toggle

Demonstrates how to use the useToggle hook to manage a boolean state and control it with buttons. It shows how to get the current value, toggle it, and set it to specific true or false values.

```jsx
import { useToggle } from 'usehooks-ts'

export default function Component() {
  const [value, toggle, setValue] = useToggle()

  // Just an example to use "setValue"
  const customToggle = () => {
    setValue((x: boolean) => !x)
  }

  return (
    <>
      <p>
        Value is <code>{value.toString()}</code>
      </p>
      <button
        onClick={() => {
          setValue(true)
        }}
      >
        set true
      </button>
      <button
        onClick={() => {
          setValue(false)
        }}
      >
        set false
      </button>
      <button onClick={toggle}>toggle</button>
      <button onClick={customToggle}>custom toggle</button>
    </>
  )
}
```

--------------------------------

### Usage Example of useCopyToClipboard

Source: https://usehooks-ts.com/react-hook/use-copy-to-clipboard

Demonstrates how to use the `useCopyToClipboard` hook in a React component to copy text to the clipboard and display the copied value. It handles both success and error cases.

```jsx
import { useCopyToClipboard } from 'usehooks-ts'

export default function Component() {
  const [copiedText, copy] = useCopyToClipboard()

  const handleCopy = (text: string) => () => {
    copy(text)
      .then(() => {
        console.log('Copied!', { text })
      })
      .catch(error => {
        console.error('Failed to copy!', error)
      })
  }

  return (
    <>
      <h1>Click to copy:</h1>
      <div style={{ display: 'flex' }}>
        <button onClick={handleCopy('A')}>A</button>
        <button onClick={handleCopy('B')}>B</button>
        <button onClick={handleCopy('C')}>C</button>
      </div>
      <p>Copied value: {copiedText ?? 'Nothing is copied yet!'}</p>
    </>
  )
}
```

--------------------------------

### Dynamically Load jQuery with useScript

Source: https://usehooks-ts.com/react-hook/use-script

This example demonstrates how to load the jQuery library using the useScript hook. It shows how to monitor the script's loading status and execute code once the script is ready. The script is configured not to be removed on component unmount.

```typescript
import { useEffect } from 'react'

import { useScript } from 'usehooks-ts'

// it's an example, use your types instead
declare const jQuery: any

export default function Component() {
  // Load the script asynchronously
  const status = useScript(`https://code.jquery.com/jquery-3.5.1.min.js`, {
    removeOnUnmount: false,
    id: 'jquery',
  })

  useEffect(() => {
    if (typeof jQuery !== 'undefined') {
      // jQuery is loaded => print the version
      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
      alert(jQuery.fn.jquery)
    }
  }, [status])

  return (
    <div>
      <p>{`Current status: ${status}`}</p>

      {status === 'ready' && <p>You can use the script here.</p>}
    </div>
  )
}

```

--------------------------------

### Usage Example for useOnClickOutside

Source: https://usehooks-ts.com/react-hook/use-on-click-outside

Demonstrates how to use the useOnClickOutside hook in a React component to trigger a callback when a click occurs outside a specific button element. Imports are required.

```javascript
import { useRef } from 'react'

import { useOnClickOutside } from 'usehooks-ts'

export default function Component() {
  const ref = useRef(null)

  const handleClickOutside = () => {
    // Your custom logic here
    console.log('clicked outside')
  }

  const handleClickInside = () => {
    // Your custom logic here
    console.log('clicked inside')
  }

  useOnClickOutside(ref, handleClickOutside)

  return (
    <button
      ref={ref}
      onClick={handleClickInside}
      style={{ width: 200, height: 200, background: 'cyan' }}
    />
  )
}
```

--------------------------------

### Basic Usage of useInterval Hook

Source: https://usehooks-ts.com/react-hook/use-interval

Demonstrates how to use the useInterval hook to create a counter that increments at a dynamic interval. The interval can be started, paused, and its delay adjusted by user input.

```jsx
import { useState } from 'react'

import type { ChangeEvent } from 'react'

import { useInterval } from 'usehooks-ts'

export default function Component() {
  // The counter
  const [count, setCount] = useState<number>(0)
  // Dynamic delay
  const [delay, setDelay] = useState<number>(1000)
  // ON/OFF
  const [isPlaying, setPlaying] = useState<boolean>(false)

  useInterval(
    () => {
      // Your custom logic here
      setCount(count + 1)
    },
    // Delay in milliseconds or null to stop it
    isPlaying ? delay : null,
  )

  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
    setDelay(Number(event.target.value))
  }

  return (
    <>
      <h1>{count}</h1>
      <button
        onClick={() => {
          setPlaying(!isPlaying)
        }}
      >
        {isPlaying ? 'pause' : 'play'}
      </button>
      <p>
        <label htmlFor="delay">Delay: </label>
        <input
          type="number"
          name="delay"
          onChange={handleChange}
          value={delay}
        />
      </p>
    </>
  )
}

```

--------------------------------

### Usage Example for useClickAnyWhere

Source: https://usehooks-ts.com/react-hook/use-click-any-where

Demonstrates how to use the useClickAnyWhere hook in a React component to track click counts anywhere on the document. Import the hook and call it with a callback function to update state.

```javascript
import { useState } from 'react'

import { useClickAnyWhere } from 'usehooks-ts'

export default function Component() {
  const [count, setCount] = useState(0)

  useClickAnyWhere(() => {
    setCount(prev => prev + 1)
  })

  return <p>Click count: {count}</p>
}
```

--------------------------------

### useCountdown API

Source: https://usehooks-ts.com/react-hook/use-countdown

The useCountdown hook manages a countdown process. It accepts options to configure the starting count, stopping condition, interval, and increment direction. It returns the current count and controller functions to start, stop, and reset the countdown.

```APIDOC
## useCountdown

Custom hook that manages countdown.

### Parameters
#### `countdownOptions` (CountdownOptions) - Required
The countdown's options.

### Returns
[`number`, `CountdownControllers`]
An array containing the countdown's count and its controllers.

### Type Aliases
#### `CountdownControllers`
**Type:** `Object`
The countdown's controllers.

**Type Declaration:**
- `resetCountdown`(): `void` - Reset the countdown.
- `startCountdown`(): `void` - Start the countdown.
- `stopCountdown`(): `void` - Stop the countdown.

#### `CountdownOptions`
**Type:** `Object`
The countdown's options.

**Type Declaration:**
- `countStart` (`number`) - Required - The countdown's starting number, initial value of the returned number.
- `countStop` (`number`) - Optional - The countdown's stopping number. Pass `-Infinity` to decrease forever. Default: `0`.
- `intervalMs` (`number`) - Optional - The countdown's interval, in milliseconds. Default: `1000`.
- `isIncrement` (`boolean`) - Optional - True if the countdown is increment. Default: `false`.
```

--------------------------------

### useResizeObserver with Debounce Callback

Source: https://usehooks-ts.com/react-hook/use-resize-observer

This example demonstrates how to use useResizeObserver with a debounced callback to update the component's state. It limits the frequency of state updates to improve performance, especially for frequent resize events.

```typescript
export function WithDebounce() {
  const ref = useRef<HTMLDivElement>(null)
  const [{ width, height }, setSize] = useState<Size>({
    width: undefined,
    height: undefined,
  })

  const onResize = useDebounceCallback(setSize, 200)

  useResizeObserver({
    ref,
    onResize,
  })

  return (
    <div
      ref={ref}
      style={{
        border: '1px solid palevioletred',
        width: '100%',
        resize: 'both',
        overflow: 'auto',
        maxWidth: '100%',
      }}
    >
      debounced: {width} x {height}
    </div>
  )
}
```

--------------------------------

### React Component Usage Example

Source: https://usehooks-ts.com/react-hook/use-ternary-dark-mode

Demonstrates how to use the useTernaryDarkMode hook in a React component to display and control dark mode settings. It shows how to access the current theme, toggle between modes, and select a specific mode.

```tsx
import { useTernaryDarkMode } from 'usehooks-ts'

type TernaryDarkMode = ReturnType<typeof useTernaryDarkMode>['ternaryDarkMode']

export default function Component() {
  const {
    isDarkMode,
    ternaryDarkMode,
    setTernaryDarkMode,
    toggleTernaryDarkMode,
  } = useTernaryDarkMode()

  return (
    <div>
      <p>Current theme: {isDarkMode ? 'dark' : 'light'}</p>
      <p>ternaryMode: {ternaryDarkMode}</p>
      <p>
        Toggle between three modes
        <button onClick={toggleTernaryDarkMode}>
          Toggle from {ternaryDarkMode}
        </button>
      </p>
      <p>
        Select a mode
        <br />
        <select
          name="select-ternaryDarkMode"
          onChange={ev => {
            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
            setTernaryDarkMode(ev.target.value as TernaryDarkMode)
          }}
          value={ternaryDarkMode}
        >
          <option value="light">light</option>
          <option value="system">system</option>
          <option value="dark">dark</option>
        </select>
      </p>
    </div>
  )
}
```

--------------------------------

### useCountdown Hook Implementation

Source: https://usehooks-ts.com/react-hook/use-countdown

The core implementation of the useCountdown hook, including options for starting count, stopping count, interval, and increment direction. It utilizes useCounter, useBoolean, and useInterval hooks.

```typescript
import { useCallback } from 'react'

import { useBoolean, useCounter, useInterval } from 'usehooks-ts'

type CountdownOptions = {
  countStart: number

  intervalMs?: number
  isIncrement?: boolean

  countStop?: number
}

type CountdownControllers = {
  startCountdown: () => void
  stopCountdown: () => void
  resetCountdown: () => void
}

export function useCountdown({
  countStart,
  countStop = 0,
  intervalMs = 1000,
  isIncrement = false,
}: CountdownOptions): [number, CountdownControllers] {
  const {
    count,
    increment,
    decrement,
    reset: resetCounter,
  } = useCounter(countStart)

  /*
   * Note: used to control the useInterval
   * running: If true, the interval is running
   * start: Should set running true to trigger interval
   * stop: Should set running false to remove interval.
   */
  const { 
    value: isCountdownRunning,
    setTrue: startCountdown,
    setFalse: stopCountdown,
  } = useBoolean(false)

  // Will set running false and reset the seconds to initial value.
  const resetCountdown = useCallback(() => {
    stopCountdown()
    resetCounter()
  }, [stopCountdown, resetCounter])

  const countdownCallback = useCallback(() => {
    if (count === countStop) {
      stopCountdown()
      return
    }

    if (isIncrement) {
      increment()
    } else {
      decrement()
    }
  }, [count, countStop, decrement, increment, isIncrement, stopCountdown])

  useInterval(countdownCallback, isCountdownRunning ? intervalMs : null)

  return [count, { startCountdown, stopCountdown, resetCountdown }]
}
```

--------------------------------

### Auto Lock Scroll on Modal Mount

Source: https://usehooks-ts.com/react-hook/use-scroll-lock

This example demonstrates how to automatically lock the body's scroll when a modal component mounts. No manual control is needed as the hook handles it on initialization.

```jsx
import { useScrollLock } from 'usehooks-ts'

// Example 1: Auto lock the scroll of the body element when the modal mounts
export default function Modal() {
  useScrollLock()
  return <div>Modal</div>
}
```

--------------------------------

### Basic Usage of useStep Hook

Source: https://usehooks-ts.com/react-hook/use-step

Demonstrates how to use the useStep hook to manage a multi-step process. It shows how to access the current step and helper functions for navigation and state management.

```javascript
import { useStep } from 'usehooks-ts'

export default function Component() {
  const [currentStep, helpers] = useStep(5)

  const {
    canGoToPrevStep,
    canGoToNextStep,
    goToNextStep,
    goToPrevStep,
    reset,
    setStep,
  } = helpers

  return (
    <>
      <p>Current step is {currentStep}</p>
      <p>Can go to previous step {canGoToPrevStep ? 'yes' : 'no'}</p>
      <p>Can go to next step {canGoToNextStep ? 'yes' : 'no'}</p>
      <button onClick={goToNextStep}>Go to next step</button>
      <button onClick={goToPrevStep}>Go to previous step</button>
      <button onClick={reset}>Reset</button>
      <button
        onClick={() => {
          setStep(3)
        }}
      >
        Set to step 3
      </button>
    </>
  )
}
```

--------------------------------

### Basic Usage of useUnmount

Source: https://usehooks-ts.com/react-hook/use-unmount

Demonstrates how to use the useUnmount hook to execute cleanup logic when a component unmounts. Import the hook and pass your cleanup function as an argument.

```javascript
import { useUnmount } from 'usehooks-ts'

export default function Component() {
  useUnmount(() => {
    // Cleanup logic here
  })

  return <div>Hello world</div>
}
```

--------------------------------

### Basic Usage of useMap Hook

Source: https://usehooks-ts.com/react-hook/use-map

Demonstrates how to initialize and use the useMap hook with basic operations like adding, resetting, and setting all entries. It also shows how to conditionally disable a button based on map content.

```jsx
import { Fragment } from 'react'

import { useMap } from 'usehooks-ts'

export default function Component() {
  const [map, actions] = useMap<string, string>([['key', '🆕']])

  const set = () => {
    actions.set(String(Date.now()), '📦')
  }
  const setAll = () => {
    actions.setAll([
      ['hello', '👋'],
      ['data', '📦'],
    ])
  }
  const reset = () => {
    actions.reset()
  }
  const remove = () => {
    actions.remove('hello')
  }

  return (
    <div>
      <button onClick={set}>Add</button>
      <button onClick={reset}>Reset</button>
      <button onClick={setAll}>Set new data</button>
      <button onClick={remove} disabled={!map.get('hello')}>
        {'Remove "hello"'}
      </button>

      <pre>
        Map (
        {Array.from(map.entries()).map(([key, value]) => (
          <Fragment key={key}>{`\n  ${key}: ${value}`}</Fragment>
        ))}
        <br />)
      </pre>
    </div>
  )
}
```

--------------------------------

### Usage Example of useIsMounted

Source: https://usehooks-ts.com/react-hook/use-is-mounted

Demonstrates how to use the useIsMounted hook within a component to safely update state after an asynchronous operation. It prevents state updates on unmounted components.

```typescript
import { useEffect, useState } from 'react'

import { useIsMounted } from 'usehooks-ts'

const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))

function Child() {
  const [data, setData] = useState('loading')
  const isMounted = useIsMounted()

  // simulate an api call and update state
  useEffect(() => {
    void delay(3000).then(() => {
      if (isMounted()) setData('OK')
    })
  }, [isMounted])

  return <p>{data}</p>
}

export default function Component() {
  const [isVisible, setVisible] = useState<boolean>(false)

  const toggleVisibility = () => {
    setVisible(state => !state)
  }

  return (
    <>
      <button onClick={toggleVisibility}>{isVisible ? 'Hide' : 'Show'}</button>

      {isVisible && <Child />}
    </>
  )
}
```

--------------------------------

### Basic Usage of useSessionStorage

Source: https://usehooks-ts.com/react-hook/use-session-storage

Demonstrates how to use the `useSessionStorage` hook to manage a counter. It shows how to initialize the state, update it with a function, and reset it by removing the value from session storage.

```javascript
import { useSessionStorage } from 'usehooks-ts'

export default function Component() {
  const [value, setValue, removeValue] = useSessionStorage('test-key', 0)

  return (
    <div>
      <p>Count: {value}</p>
      <button
        onClick={() => {
          setValue((x: number) => x + 1)
        }}
      >
        Increment
      </button>
      <button
        onClick={() => {
          setValue((x: number) => x - 1)
        }}
      >
        Decrement
      </button>
      <button
        onClick={() => {
          removeValue()
        }}
      >
        Reset
      </button>
    </div>
  )
}
```

--------------------------------

### useWindowSize Hook Implementation

Source: https://usehooks-ts.com/react-hook/use-window-size

This is the core implementation of the `useWindowSize` hook. It handles window resizing events, supports debouncing, and manages initial values for SSR compatibility.

```typescript
import { useState } from 'react'

import {
  useDebounceCallback,
  useEventListener,
  useIsomorphicLayoutEffect,
} from 'usehooks-ts'

type WindowSize<T extends number | undefined = number | undefined> = {
  width: T
  height: T
}

type UseWindowSizeOptions<InitializeWithValue extends boolean | undefined> = {
  initializeWithValue: InitializeWithValue
  debounceDelay?: number
}

const IS_SERVER = typeof window === 'undefined'

// SSR version of useWindowSize.
export function useWindowSize(options: UseWindowSizeOptions<false>): WindowSize
// CSR version of useWindowSize.
export function useWindowSize(
  options?: Partial<UseWindowSizeOptions<true>>,
): WindowSize<number>
export function useWindowSize(
  options: Partial<UseWindowSizeOptions<boolean>> = {},
): WindowSize | WindowSize<number> {
  let { initializeWithValue = true } = options
  if (IS_SERVER) {
    initializeWithValue = false
  }

  const [windowSize, setWindowSize] = useState<WindowSize>(() => {
    if (initializeWithValue) {
      return {
        width: window.innerWidth,
        height: window.innerHeight,
      }
    }
    return {
      width: undefined,
      height: undefined,
    }
  })

  const debouncedSetWindowSize = useDebounceCallback(
    setWindowSize,
    options.debounceDelay,
  )

  function handleSize() {
    const setSize = options.debounceDelay
      ? debouncedSetWindowSize
      : setWindowSize

    setSize({
      width: window.innerWidth,
      height: window.innerHeight,
    })
  }

  useEventListener('resize', handleSize)

  // Set size at the first client-side load
  useIsomorphicLayoutEffect(() => {
    handleSize()
  }, [])

  return windowSize
}

```

--------------------------------

### Basic Usage of useReadLocalStorage

Source: https://usehooks-ts.com/react-hook/use-read-local-storage

Demonstrates how to use the useReadLocalStorage hook to retrieve a value from localStorage. Assumes a value with the key 'darkMode' has already been set.

```javascript
import { useReadLocalStorage } from 'usehooks-ts'

export default function Component() {
  // Assuming a value was set in localStorage with this key
  const darkMode = useReadLocalStorage('darkMode')

  return <p>DarkMode is {darkMode ? 'enabled' : 'disabled'}</p>
}
```

--------------------------------

### useResizeObserver Hook Implementation

Source: https://usehooks-ts.com/react-hook/use-resize-observer

This snippet contains the full implementation of the `useResizeObserver` hook, including type definitions, state management, and the ResizeObserver logic. It handles different box sizing options and provides a callback for size changes.

```typescript
import { useEffect, useRef, useState } from 'react'

import type { RefObject } from 'react'

import { useIsMounted } from 'usehooks-ts'

type Size = {
  width: number | undefined
  height: number | undefined
}

type UseResizeObserverOptions<T extends HTMLElement = HTMLElement> = {
  ref: RefObject<T>
  onResize?: (size: Size) => void
  box?: 'border-box' | 'content-box' | 'device-pixel-content-box'
}

const initialSize: Size = {
  width: undefined,
  height: undefined,
}

export function useResizeObserver<T extends HTMLElement = HTMLElement>(
  options: UseResizeObserverOptions<T>,
): Size {
  const { ref, box = 'content-box' } = options
  const [{ width, height }, setSize] = useState<Size>(initialSize)
  const isMounted = useIsMounted()
  const previousSize = useRef<Size>({ ...initialSize })
  const onResize = useRef<((size: Size) => void) | undefined>(undefined)
  onResize.current = options.onResize

  useEffect(() => {
    if (!ref.current) return

    if (typeof window === 'undefined' || !('ResizeObserver' in window)) return

    const observer = new ResizeObserver(([entry]) => {
      const boxProp =
        box === 'border-box'
          ? 'borderBoxSize'
          : box === 'device-pixel-content-box'
            ? 'devicePixelContentBoxSize'
            : 'contentBoxSize'

      const newWidth = extractSize(entry, boxProp, 'inlineSize')
      const newHeight = extractSize(entry, boxProp, 'blockSize')

      const hasChanged =
        previousSize.current.width !== newWidth ||
        previousSize.current.height !== newHeight

      if (hasChanged) {
        const newSize: Size = { width: newWidth, height: newHeight }
        previousSize.current.width = newWidth
        previousSize.current.height = newHeight

        if (onResize.current) {
          onResize.current(newSize)
        } else {
          if (isMounted()) {
            setSize(newSize)
          }
        }
      }
    })

    observer.observe(ref.current, { box })

    return () => {
      observer.disconnect()
    }
  }, [box, ref, isMounted])

  return { width, height }
}

type BoxSizesKey = keyof Pick<
  ResizeObserverEntry,
  'borderBoxSize' | 'contentBoxSize' | 'devicePixelContentBoxSize'
>

function extractSize(
  entry: ResizeObserverEntry,
  box: BoxSizesKey,
  sizeType: keyof ResizeObserverSize,
): number | undefined {
  if (!entry[box]) {
    if (box === 'contentBoxSize') {
      return entry.contentRect[sizeType === 'inlineSize' ? 'width' : 'height']
    }
    return undefined
  }

  return Array.isArray(entry[box])
    ? entry[box][0][sizeType]
    : // @ts-ignore Support Firefox's non-standard behavior
      (entry[box][sizeType] as number)
}

```

--------------------------------

### Full Implementation of useDarkMode Hook

Source: https://usehooks-ts.com/react-hook/use-dark-mode

Provides the complete source code for the `useDarkMode` hook, including its dependencies and type definitions. It handles initialization with OS preferences and local storage.

```javascript
import {
  useIsomorphicLayoutEffect,
  useLocalStorage,
  useMediaQuery,
} from 'usehooks-ts'

const COLOR_SCHEME_QUERY = '(prefers-color-scheme: dark)'
const LOCAL_STORAGE_KEY = 'usehooks-ts-dark-mode'

type DarkModeOptions = {
  defaultValue?: boolean
  localStorageKey?: string
  initializeWithValue?: boolean
}

type DarkModeReturn = {
  isDarkMode: boolean
  toggle: () => void
  enable: () => void
  disable: () => void
  set: (value: boolean) => void
}

export function useDarkMode(options: DarkModeOptions = {}): DarkModeReturn {
  const {
    defaultValue,
    localStorageKey = LOCAL_STORAGE_KEY,
    initializeWithValue = true,
  } = options

  const isDarkOS = useMediaQuery(COLOR_SCHEME_QUERY, {
    initializeWithValue,
    defaultValue,
  })
  const [isDarkMode, setDarkMode] = useLocalStorage<boolean>(
    localStorageKey,
    defaultValue ?? isDarkOS ?? false,
    { initializeWithValue },
  )

  // Update darkMode if os prefers changes
  useIsomorphicLayoutEffect(() => {
    if (isDarkOS !== isDarkMode) {
      setDarkMode(isDarkOS)
    }
  }, [isDarkOS])

  return {
    isDarkMode,
    toggle: () => {
      setDarkMode(prev => !prev)
    },
    enable: () => {
      setDarkMode(true)
    },
    disable: () => {
      setDarkMode(false)
    },
    set: value => {
      setDarkMode(value)
    },
  }
}

```

--------------------------------

### useWindowSize

Source: https://usehooks-ts.com/react-hook/use-window-size

Custom hook that tracks the size of the window. It can be configured with options for debouncing and initial value in SSR.

```APIDOC
## useWindowSize

Custom hook that tracks the size of the window.

### Parameters

`options` (UseWindowSizeOptions<false>): The options for customizing the behavior of the hook (optional).

### Returns

`WindowSize`: An object containing the width and height of the window.

---

## useWindowSize

Custom hook that tracks the size of the window.

### Parameters

`options?` (Partial<UseWindowSizeOptions<true>>): The options for customizing the behavior of the hook (optional).

### Returns

`WindowSize<number>`: An object containing the width and height of the window.

### Type Aliases

Ƭ **UseWindowSizeOptions** <`InitializeWithValue`>

Hook options.

#### Type parameters

`InitializeWithValue` (extends `boolean` | `undefined`): If `true` (default), the hook will initialize reading the window size. In SSR, you should set it to `false`, returning `undefined` initially.

#### Type declaration

`debounceDelay?` (number): The delay in milliseconds before the state is updated (disabled by default for retro-compatibility). Default: `undefined`
`initializeWithValue` (InitializeWithValue): If `true` (default), the hook will initialize reading the window size. In SSR, you should set it to `false`, returning `undefined` initially. Default: `true`

Ƭ **WindowSize** <`T`>

Represent the dimension of the window.

#### Type parameters

`T` (extends `number` | `undefined` = `number` | `undefined`): The type of the dimension (number or undefined).

#### Type declaration

`height` (T): The height of the window.
`width` (T): The width of the window.
```

--------------------------------

### Manual Scroll Lock/Unlock for Target Element

Source: https://usehooks-ts.com/react-hook/use-scroll-lock

This example shows how to manually control scroll locking for a specific scrollable div. The `autoLock` option is set to false, and the `lock` and `unlock` functions are used to toggle the scroll state via button clicks.

```jsx
import { useScrollLock } from 'usehooks-ts'

// Example 2: Manually lock and unlock the scroll for a specific target
export function App() {
  const { lock, unlock } = useScrollLock({
    autoLock: false,
    lockTarget: '#scrollable',
  })

  return (
    <>
      <div id="scrollable" style={{ maxHeight: '50vh', overflow: 'scroll' }}>
        {['red', 'blue', 'green'].map(color => (
          <div key={color} style={{ backgroundColor: color, height: '30vh' }} />
        ))}
      </div>

      <div style={{ gap: 16, display: 'flex' }}>
        <button onClick={lock}>Lock</button>
        <button onClick={unlock}>Unlock</button>
      </div>
    </>
  )
}
```

--------------------------------

### useMediaQuery

Source: https://usehooks-ts.com/react-hook/use-media-query

Tracks the state of a media query. It returns `true` if the query matches and `false` otherwise. It can also accept options to customize its behavior, such as setting a default value or controlling initial value on server-side rendering.

```APIDOC
## useMediaQuery

Custom hook that tracks the state of a media query using the `Match Media API`.

### Parameters

- **query** (`string`) - Required - The media query to track.
- **options?** (`UseMediaQueryOptions`) - Optional - The options for customizing the behavior of the hook.
  - **defaultValue?** (`boolean`) - Optional - The default value to return if the hook is being run on the server. Defaults to `false`.
  - **initializeWithValue?** (`boolean`) - Optional - If `true` (default), the hook will initialize reading the media query. In SSR, you should set it to `false`, returning `options.defaultValue` or `false` initially. Defaults to `true`.

### Returns

- `boolean` - The current state of the media query (true if the query matches, false otherwise).
```

--------------------------------

### Use useIsClient in a React Component

Source: https://usehooks-ts.com/react-hook/use-is-client

Demonstrates how to use the useIsClient hook to conditionally render content based on whether the code is running in the browser. Import the hook and call it within your component.

```javascript
import { useIsClient } from 'usehooks-ts'

export default function Component() {
  const isClient = useIsClient()

  return <div>{isClient ? 'Client' : 'server'}</div>
}
```

--------------------------------

### useMap Hook API

Source: https://usehooks-ts.com/react-hook/use-map

Documentation for the useMap hook, including its type parameters, parameters, and return type.

```APIDOC
## useMap <K, V>(initialState?: MapOrEntries<K, V>): UseMapReturn<K, V>

Custom hook that manages a key-value `Map` state with setter actions.

### Type parameters
* `K`: The type of keys in the map.
* `V`: The type of values in the map.

### Parameters
* `initialState` (MapOrEntries<K, V>, optional): The initial state of the map as a Map or an array of key-value pairs.

### Returns
`UseMapReturn<K, V>`: A tuple containing the map state and actions to interact with the map.

### Type Aliases
#### MapOrEntries <K, V>
Represents the type for either a Map or an array of key-value pairs.
* `K`: The type of keys in the map.
* `V`: The type of values in the map.

#### UseMapActions <K, V>
Represents the actions available to interact with the map state.
* `K`: The type of keys in the map.
* `V`: The type of values in the map.

##### Type declaration
* `remove`: (`key`: K) => `void` - Remove a key-value pair from the map.
* `reset`: `Map<K, V>['clear']` - Reset the map to an empty state.
* `set`: (`key`: K, `value`: V) => `void` - Set a key-value pair in the map.
* `setAll`: (`entries`: MapOrEntries<K, V>) => `void` - Set all key-value pairs in the map.

#### UseMapReturn <K, V>
Represents the return type of the `useMap` hook. We hide some setters from the returned map to disable autocompletion.
* `K`: The type of keys in the map.
* `V`: The type of values in the map.
```

--------------------------------

### Basic Usage of useResizeObserver

Source: https://usehooks-ts.com/react-hook/use-resize-observer

Observes the size of a div element and displays its width and height. It uses the 'border-box' option to include padding and border in the observed size.

```typescript
import { useRef, useState } from 'react'

import { useDebounceCallback, useResizeObserver } from 'usehooks-ts'

type Size = {
  width?: number
  height?: number
}

export default function Component() {
  const ref = useRef<HTMLDivElement>(null)
  const { width = 0, height = 0 } = useResizeObserver({
    ref,
    box: 'border-box',
  })

  return (
    <div ref={ref} style={{ border: '1px solid palevioletred', width: '100%' }}>
      {width} x {height}
    </div>
  )
}
```

--------------------------------

### Basic Usage of useIntersectionObserver

Source: https://usehooks-ts.com/react-hook/use-intersection-observer

This snippet demonstrates the basic usage of the useIntersectionObserver hook. It sets up a component that renders multiple sections, and the hook tracks when each section becomes visible in the viewport. The 'threshold' option is set to 0.5, meaning the callback will fire when 50% of the element is visible.

```javascript
import { useIntersectionObserver } from 'usehooks-ts'

const Section = (props: { title: string }) => {
  const { isIntersecting, ref } = useIntersectionObserver({
    threshold: 0.5,
  })

  console.log(`Render Section ${props.title}`, {
    isIntersecting,
  })

  return (
    <div
      ref={ref}
      style={{
        minHeight: '100vh',
        display: 'flex',
        border: '1px dashed #000',
        fontSize: '2rem',
      }}
    >
      <div style={{ margin: 'auto' }}>{props.title}</div>
    </div>
  )
}

export default function Component() {
  return (
    <>
      {Array.from({ length: 5 }).map((_, index) => (
        <Section key={index + 1} title={`${index + 1}`} />
      ))}
    </>
  )
}
```

--------------------------------

### useLocalStorage Hook Implementation

Source: https://usehooks-ts.com/react-hook/use-local-storage

This is the core implementation of the `useLocalStorage` hook. It manages state, reads from and writes to local storage, and synchronizes changes across browser contexts.

```typescript
import { useCallback, useEffect, useState } from 'react'

import type { Dispatch, SetStateAction } from 'react'

import { useEventCallback, useEventListener } from 'usehooks-ts'

declare global {
  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
  interface WindowEventMap {
    'local-storage': CustomEvent
  }
}

type UseLocalStorageOptions<T> = {
  serializer?: (value: T) => string
  deserializer?: (value: string) => T
  initializeWithValue?: boolean
}

const IS_SERVER = typeof window === 'undefined'

export function useLocalStorage<T>(
  key: string,
  initialValue: T | (() => T),
  options: UseLocalStorageOptions<T> = {},
): [T, Dispatch<SetStateAction<T>>, () => void] {
  const { initializeWithValue = true } = options

  const serializer = useCallback<(value: T) => string>(
    value => {
      if (options.serializer) {
        return options.serializer(value)
      }

      return JSON.stringify(value)
    },
    [options],
  )

  const deserializer = useCallback<(value: string) => T>(
    value => {
      if (options.deserializer) {
        return options.deserializer(value)
      }
      // Support 'undefined' as a value
      if (value === 'undefined') {
        return undefined as unknown as T
      }

      const defaultValue =
        initialValue instanceof Function ? initialValue() : initialValue

      let parsed: unknown
      try {
        parsed = JSON.parse(value)
      } catch (error) {
        console.error('Error parsing JSON:', error)
        return defaultValue // Return initialValue if parsing fails
      }

      return parsed as T
    },
    [options, initialValue],
  )

  // Get from local storage then
  // parse stored json or return initialValue
  const readValue = useCallback((): T => {
    const initialValueToUse =
      initialValue instanceof Function ? initialValue() : initialValue

    // Prevent build error "window is undefined" but keep working
    if (IS_SERVER) {
      return initialValueToUse
    }

    try {
      const raw = window.localStorage.getItem(key)
      return raw ? deserializer(raw) : initialValueToUse
    } catch (error) {
      console.warn(`Error reading localStorage key “${key}”:`, error)
      return initialValueToUse
    }
  }, [initialValue, key, deserializer])

  const [storedValue, setStoredValue] = useState(() => {
    if (initializeWithValue) {
      return readValue()
    }

    return initialValue instanceof Function ? initialValue() : initialValue
  })

  // Return a wrapped version of useState's setter function that ...
  // ... persists the new value to localStorage.
  const setValue: Dispatch<SetStateAction<T>> = useEventCallback(value => {
    // Prevent build error "window is undefined" but keeps working
    if (IS_SERVER) {
      console.warn(
        `Tried setting localStorage key “${key}” even though environment is not a client`,
      )
    }

    try {
      // Allow value to be a function so we have the same API as useState
      const newValue = value instanceof Function ? value(readValue()) : value

      // Save to local storage
      window.localStorage.setItem(key, serializer(newValue))

      // Save state
      setStoredValue(newValue)

      // We dispatch a custom event so every similar useLocalStorage hook is notified
      window.dispatchEvent(new StorageEvent('local-storage', { key }))
    } catch (error) {
      console.warn(`Error setting localStorage key “${key}”:`, error)
    }
  })

  const removeValue = useEventCallback(() => {
    // Prevent build error "window is undefined" but keeps working
    if (IS_SERVER) {
      console.warn(
        `Tried removing localStorage key “${key}” even though environment is not a client`,
      )
    }

    const defaultValue =
      initialValue instanceof Function ? initialValue() : initialValue

    // Remove the key from local storage
    window.localStorage.removeItem(key)

    // Save state with default value
    setStoredValue(defaultValue)

    // We dispatch a custom event so every similar useLocalStorage hook is notified
    window.dispatchEvent(new StorageEvent('local-storage', { key }))
  })

  useEffect(() => {
    setStoredValue(readValue())
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [key])

  const handleStorageChange = useCallback(
    (event: StorageEvent | CustomEvent) => {
      if ((event as StorageEvent).key && (event as StorageEvent).key !== key) {
        return
      }
      setStoredValue(readValue())
    },
    [key, readValue],
  )

  // this only works for other documents, not the current one
  useEventListener('storage', handleStorageChange)

  // this is a custom event, triggered in writeValueToLocalStorage
  // See: useLocalStorage()
  useEventListener('local-storage', handleStorageChange)

  return [storedValue, setValue, removeValue]
}
```

--------------------------------

### useEventListener for Window

Source: https://usehooks-ts.com/react-hook/use-event-listener

Attaches an event listener to the window object. This overload is suitable for global window events.

```APIDOC
## useEventListener<K>

### Description
Custom hook that attaches event listeners to DOM elements, the window, or media query lists.

### Type parameters
* `K` extends keyof WindowEventMap

### Parameters
* `eventName` (K): The name of the event to listen for.
* `handler` ((event: WindowEventMap[K]) => void): The event handler function.
* `element?` (undefined): This parameter is unused in this overload, indicating window-level events.
* `options?` (boolean | AddEventListenerOptions): An options object that specifies characteristics about the event listener.

### Returns
`void`
```

--------------------------------

### useUnmount

Source: https://usehooks-ts.com/react-hook/use-unmount

Runs a cleanup function when the component is unmounted. Accepts a function as an argument, which will be executed during the unmount phase.

```APIDOC
## useUnmount

### Description
Custom hook that runs a cleanup function when the component is unmounted.

### Parameters
#### Function Parameter
- **func** (() => void) - Required - The cleanup function to be executed on unmount.

### Returns
`void`
```
Tokens:
Raw