✨ React Hooks

A collection of hooks for better state management.

Advantages of using this library:

• Negligible bundle size (supports tree shaking, ≈400B per hook import 🤏).
• Very detailed documentation along with previews and live demos.
• Highly performant (no unnecessary rerenders at all).
• Super flexible (providing options whenever possible).
• Easily extendable: Since it's tree-shakable, any new useful hooks can be added in the future without having to worry about bundle size.

📕 Table of Content

• Installation
• Hooks
• Usage
• Contributions
• License

⬇️ Installation

npm i @mhmdjawhar/react-hooks

🪝 Hooks

• useDisclosure
• useClickOutside
• useViewportSize
• useResizeObserver
• useWindowScroll
• useSystemColorScheme
• useWindowEvent
• useResetChild
• useLocalStorage
• useTimeout
• useInterval
• useDebounce
• useAnimationFrame
• useMediaQuery

🔎 Usage

useDisclosure

Used to manage boolean state and controlled components.

Examples

import { useDisclosure } from '@mhmdjawhar/react-hooks'

export const Demo = () => {
  const [opened, { close, open, toggle }] = useDisclosure()

  return (
    <>
      <button onClick={open}>open</button>&emsp;&emsp;
      <button onClick={close}>close</button>&emsp;&emsp;
      <button onClick={toggle}>toggle</button>
      <p>{opened ? 'opened' : 'closed'}</p>
    </>
  )
}

Parameters

| Name | Type | Description | | ------------ | --------- | ------------------------------------------------------- | | initialValue | boolean | (Optional) Initial opened state. Defaults to false. |

Return Value

Returns an array with the following elements:

| Name | Type | Description | | ------------ | --------- | -------------------------------------------- | | [0] | boolean | The current state of the disclosure. | | [1].open | Function | A function that sets the state to true. | | [1].close | Function | A function that sets the state to false. | | [1].toggle | Function | A function that toggles the boolean state. |

useClickOutside

Detects click or an optional given event outside of a given element or list of elements.

Examples

import { useClickOutside } from '@mhmdjawhar/react-hooks'
import { useCallback, useState } from 'react'

export const ClickOutsideExample: React.FC = () => {
  const [count, setCount] = useState(0)

  const handler = useCallback(() => {
    setCount((c) => c + 1)
    console.log('outside was clicked')
  }, [])

  const ref = useClickOutside<HTMLDivElement>(handler)

  return (
    <>
      <div ref={ref} style={{ width: '400px', height: '400px', backgroundColor: 'black' }} />
      <p>Click outside count: {count}</p>
    </>
  )
}

You can also specify multiple nodes. The nodes in the list won't trigger the outside click event.

import { useClickOutside } from '@mhmdjawhar/react-hooks'
import { useCallback, useRef, useState } from 'react'

export const ClickOutsideMultipleExample: React.FC = () => {
  const [count, setCount] = useState(0)

  const redBoxRef = useRef<HTMLDivElement>(null)
  const blackBoxRef = useRef<HTMLDivElement>(null)

  const handler = useCallback(() => {
    setCount((c) => c + 1)
    console.log('outside was clicked')
  }, [])

  useClickOutside(handler, [redBoxRef, blackBoxRef])

  return (
    <>
      {/* first element */}
      <div ref={redBoxRef} style={{ width: '400px', height: '400px', backgroundColor: 'red' }} />
      {/* second element */}
      <div ref={blackBoxRef} style={{ width: '400px', height: '400px', backgroundColor: 'black' }} />
      <p>Click outside count: {count}</p>
    </>
  )
}

You can also specify another event to replace the default click event.

import { useClickOutside } from '@mhmdjawhar/react-hooks'
import { useCallback, useState } from 'react'

export const OutsideEventExample: React.FC = () => {
  const [count, setCount] = useState(0)

  const handler = useCallback(() => {
    setCount((prevCount) => prevCount + 1)
    console.log('outside was clicked')
  }, [])

  const ref = useClickOutside<HTMLDivElement>(handler, null, 'mousedown')

  return (
    <>
      <div ref={ref} style={{ width: '400px', height: '400px', backgroundColor: 'black' }} />
      <p>Click outside count: {count}</p>
    </>
  )
}

Parameters

| Name | Type | Description | | ------- | ------------------------ | ----------------------------------------------------------------------------------- | | handler | Function | A callback function triggered when outside click is detected. | | refs | RefObject[] | (Optional) List of RefObjects for elements that should not trigger outside click. | | event | keyof DocumentEventMap | (Optional) Event to replace the default click event. |

Return Value

| Name | Type | Description | | ---- | ----------- | ------------------------------------------------------------- | | ref | RefObject | Must be passed to the element to detect clicks outside of it. |

useViewportSize

Returns current viewport's width and height. It updates on resize and orientationchange.

Examples

import { useViewportSize } from '@mhmdjawhar/react-hooks'

export const ViewportSizeExample: React.FC = () => {
  const { width, height } = useViewportSize()

  return (
    <p>
      width: {width}, height: {height}
    </p>
  )
}

You can also pass an optional boolean parameter to disable or enable debouncing the resize update. It is set true by default to optimize and avoid too many rerenders. to Set to false to disable debouncing and get instant updates.

import { useViewportSize } from '@mhmdjawhar/react-hooks'
import { useState } from 'react'

export const ViewportSizeSubscriptionExample: React.FC = () => {
  const [debounce, setDebounce] = useState(true)

  const { width, height } = useViewportSize(debounce)

  return (
    <>
      <p>
        width: {width}, height: {height}
      </p>
      <button onClick={() => setDebounce((prev) => !prev)}>toggle debounce</button>
    </>
  )
}

Parameters

| Name | Type | Description | | -------- | --------- | ---------------------------------------------------------------------------------------------------------------- | | debounce | boolean | (Optional) Debounce updating the size. Set to false to disable debouncing. true by default for optimization. |

Return Value

Returns an object with the following properties:

| Name | Type | Description | | ------ | -------- | -------------------- | | width | number | The viewport width. | | height | number | The viewport height. |

useResizeObserver

Detects changes to the dimensions of an Element with ResizeObserver.

Examples

import { useResizeObserver } from '@mhmdjawhar/react-hooks'
import { useState } from 'react'

export const ResizeObserverExample: React.FC = () => {
  const [rect, setRect] = useState({
    x: 0,
    y: 0,
    width: 0,
    height: 0,
    top: 0,
    left: 0,
    bottom: 0,
    right: 0
  })

  const ref = useResizeObserver<HTMLTextAreaElement>((contentRect) => subscription && setRect(contentRect))

  return (
    <>
      <textarea ref={ref} style={{ width: '400px', height: '400px', position: 'relative' }} />
      <p>
        width: {rect.width}, height: {rect.height}
      </p>
      <p>
        x: {rect.x}, y: {rect.y}
      </p>
      <p>
        top: {rect.top}, left: {rect.left}, bottom: {rect.bottom}, right: {rect.right}
      </p>
    </>
  )
}

You can also pass a list of dependencies used in the callback function.

import { useResizeObserver } from '@mhmdjawhar/react-hooks'
import { useState } from 'react'

export const ResizeObserverExample: React.FC = () => {
  const [rect, setRect] = useState({
    x: 0,
    y: 0,
    width: 0,
    height: 0,
    top: 0,
    left: 0,
    bottom: 0,
    right: 0
  })

  const [subscription, setSubscription] = useState(true)

  const ref = useResizeObserver<HTMLTextAreaElement>(
    (contentRect) => subscription && setRect(contentRect),
    [subscription]
  )

  return (
    <>
      <textarea ref={ref} style={{ width: '400px', height: '400px', position: 'relative' }} />
      <p>
        width: {rect.width}, height: {rect.height}
      </p>
      <p>
        x: {rect.x}, y: {rect.y}
      </p>
      <p>
        top: {rect.top}, left: {rect.left}, bottom: {rect.bottom}, right: {rect.right}
      </p>
      <button onClick={() => setSubscription((sub) => !sub)}>toggle subscription</button>
    </>
  )
}

Parameters

| Name | Type | Description | | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | | handler | Function | A function called when the size of the element observed changes. contentRect values are passed as an object parameter. | | depsList | DependencyList | (Optional) List of dependencies used in the handler. Pass state values that the handler might depend on. | | options | ResizeObserver | (Optional) ResizeObserver options. |

Return Value

| Name | Type | Description | | ---- | ----------- | ----------------------------------------------------------- | | ref | RefObject | Must be passed to the element whose size is being observed. |

useWindowScroll

Returns current window scroll position and a function to scroll to a given position.

Examples

import { useWindowScroll } from '@mhmdjawhar/react-hooks'

export const WindowScrollExample: React.FC = () => {
  const [position, scrollTo] = useWindowScroll()

  return (
    <>
      <p>
        Scroll position - X: {position.x}, Y: {position.y}
      </p>
      <button onClick={() => scrollTo({ y: 0 })}>scroll to top</button>
    </>
  )
}

You can also pass an optional boolean parameter to either activate or cancel subscription. Set to false to stop getting updates.

import { useWindowScroll } from '@mhmdjawhar/react-hooks'
import { useState } from 'react'

export const WindowScrollExample: React.FC = () => {
  const [subscription, setSubscription] = useState(true)

  const [position, scrollTo] = useWindowScroll(subscription)

  return (
    <>
      <p>
        Scroll position - width: {position.x}, height: {position.y}
      </p>
      <button onClick={() => scrollTo({ y: 0 })}>scroll to top</button>
      <button onClick={() => setSubscription((prev) => !prev)}>toggle subscription</button>
    </>
  )
}

Parameters

| Name | Type | Description | | ------------ | --------- | ----------------------------------------------------------------------------------- | | isSubscribed | boolean | (Optional) Activate or cancel subscription. Set to false to stop getting updates. |

Return Value

Returns an array with the following elements:

| Name | Type | Description | | ------- | -------- | -------------------------------------------------- | | [0].x | number | Scroll position X. | | [0].y | number | Scroll position Y. | | [1] | Function | A function to scroll smoothly to a given position. |

useSystemColorScheme

Returns current system color scheme. Updates on change.

Examples

import { useSystemColorScheme } from '@mhmdjawhar/react-hooks'

export const SystemColorSchemeExample: React.FC = () => {
  const colorScheme = useSystemColorScheme()

  return <p>{colorScheme}</p>
}

Return Value

| Name | Type | Description | | ----------- | -------- | ------------------ | | colorScheme | string | light or dark. |

useWindowEvent

Adds an event listener to window object when the component mounts and removes it when it unmounts.

Examples

import { useWindowEvent } from '@mhmdjawhar/react-hooks'
import { useCallback, useState } from 'react'

export const WindowEventExample: React.FC = () => {
  const [key, setKey] = useState('nothing')

  const windowListener = useCallback((event: KeyboardEvent) => {
    setKey(event.key)
  }, [])

  useWindowEvent('keydown', windowListener)

  return <p>{key} was pressed</p>
}

Parameters

| Name | Type | Description | | -------- | ------------------------------------ | --------------------------- | | type | keyof WindowEventMap | Type of event. | | listener | Function | event listener. | | options | boolean \| AddEventListenerOptions | (Optional) event options. |

useResetChild

Resets the state of a child component along with all its children. Note that it does not reset the state of the current component.

Examples

import { useResetChild } from '@mhmdjawhar/react-hooks'
import { useState } from 'react'

export const ResetChildExample = () => {
  const [resetKey, reset] = useResetChild()

  return (
    <>
      <ChildComponent key={resetKey} />
      <button onClick={reset}>reset child component</button>
    </>
  )
}

const ChildComponent = () => {
  const [count, setCount] = useState(0)

  return (
    <div>
      <p>Child Component</p>
      <button onClick={() => setCount((c) => c + 1)}>count: {count}</button>
      <SubChildComponent />
    </div>
  )
}

const SubChildComponent = () => {
  const [count, setCount] = useState(0)

  return (
    <div>
      <p>Subchild Component</p>
      <button onClick={() => setCount((c) => c + 1)}>count: {count}</button>
    </div>
  )
}

Parameters

| Name | Type | Description | | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | prefixKey | string | (Optional) In case multiple instances of this hook are being used to reset sibling components. Pass a unique prefix value to avoid key collisions. |

Return Value

Returns an array with the following elements:

| Name | Type | Description | | ----- | -------- | ------------------------------------------------------- | | [0] | string | Reset value that must be passed to the component key. | | [1] | Function | A reset function to trigger the reset. |

useTimeout

Manages timeout and handles starting and clearing it.

Examples

import { useTimeout } from '@mhmdjawhar/react-hooks'
import { useState } from 'react'

export const TimeoutExample: React.FC = () => {
  const [count, setCount] = useState(0)
  const [start, clear] = useTimeout(() => setCount((c) => c + 1), 1000)

  return (
    <>
      <button onClick={start}>Start Timeout</button>
      <button onClick={clear}>Clear Timeout</button>
      <p>count: {count}</p>
    </>
  )
}

Parameters

| Name | Type | Description | | ---------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | callback | Function | A function that will be called after the timer elapses. | | delay | number | timeout delay (ms) after which the callback function will be executed. | | autoInvoke | boolean | (Optional) Determines whether the timeout should start when the component mounts. false by default. | | depsList | React.DependencyList | (Optional) List of dependencies used in the callback function. Pass state values that the callback function might depend on. Empty by default. |

Return Value

Returns an array with the following elements:

| Name | Type | Description | | ----- | -------- | ------------------------- | | [0] | Function | Start timeout function. | | [1] | Function | Clear timeout function. |

useInterval

Manages interval and handles starting and clearing it.

Examples

import { useInterval } from '@mhmdjawhar/react-hooks'
import { useState } from 'react'

export const IntervalExample: React.FC = () => {
  const [count, setCount] = useState(0)
  const [start, clear, isActive] = useInterval(() => setCount((c) => c + 1), 1000)
  const [status, setStatus] = useState('')

  const checkIntervalStatus = () => {
    if (isActive()) {
      setStatus('running')
    } else {
      setStatus('idle')
    }
  }

  return (
    <>
      <button onClick={start}>Start</button>
      <button onClick={clear}>Clear</button>
      <p>count: {count}</p>
      <button onClick={checkIntervalStatus}>check interval status</button>
      <p>Interval state: {status}</p>
    </>
  )
}

Parameters

| Name | Type | Description | | ---------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | callback | Function | A function that will be called every delay. | | delay | number | interval delay (ms) in between callback executions. | | autoInvoke | boolean | (Optional) Determines whether the interval should start when the component mounts. false by default. | | depsList | React.DependencyList | (Optional) List of dependencies used in the callback function. Pass state values that the callback function might depend on. Empty by default. |

Return Value

Returns an array with the following elements:

| Name | Type | Description | | ----- | -------- | ------------------------------------------------- | | [0] | Function | Start interval function. | | [1] | Function | Clear interval function. | | [2] | Function | A function to check the status of the interval. |

useAnimationFrame

Manages requestAnimationFrame and handles starting and cancelling it.

Examples

import { useAnimationFrame } from '@mhmdjawhar/react-hooks'
import { useRef, useState } from 'react'

export const RequestAnimationFrameExample: React.FC = () => {
  const boxRef = useRef<HTMLDivElement>(null)

  // Animation that moves a div 400px over 2 seconds
  const [start, , isActive] = useAnimationFrame(({ timestamp, startTime, complete }) => {
    const runTime = timestamp - startTime
    const duration = 2000
    const distance = 400
    let progress = runTime / duration
    progress = Math.min(progress, 1)

    if (boxRef.current) {
      boxRef.current.style.left = (distance * progress).toFixed(2) + 'px'
    }

    // if duration is met stop animation by calling complete()
    if (runTime >= duration) {
      complete(() => checkAnimationStatus())
    }
  })

  const [status, setStatus] = useState('idle')

  const checkAnimationStatus = () => {
    if (isActive()) {
      setStatus('running')
    } else {
      setStatus('idle')
    }
  }

  const startAnimation = () => {
    start()
    checkAnimationStatus()
  }

  return (
    <>
      <button onClick={startAnimation}>Start</button>
      <div ref={boxRef} style={{ width: '100px', height: '100px', background: 'purple', position: 'relative' }} />
      <button onClick={checkAnimationStatus}>check animation status</button>
      <p>Animation state: {status}</p>
    </>
  )
}

Just like useTimeout and useInterval, useAnimationFrame also returns a cancel function that you can use to stop the animation from running.

import { useAnimationFrame } from '@mhmdjawhar/react-hooks'
import { useRef } from 'react'

export const RequestAnimationFrameCancelExample: React.FC = () => {
  const boxRef = useRef<HTMLDivElement>(null)
  const rightRef = useRef<number>(0)
  const leftRef = useRef<number>(400)

  // Animation that moves the div 400px to the right over 2 seconds
  const [startMoveRight, cancelMoveRight] = useAnimationFrame(({ complete }) => {
    if (boxRef.current) {
      // run animation as long as distance is not met, otherwise call complete()
      if (rightRef.current < 400) {
        ++rightRef.current
        boxRef.current.style.left = rightRef.current + 'px'
      } else {
        complete(() => {
          rightRef.current = 0
          startMoveLeft()
        })
      }
    }
  })

  // Animation that moves the div 400px to the left over 2 seconds
  const [startMoveLeft, cancelMoveLeft] = useAnimationFrame(({ complete }) => {
    if (boxRef.current) {
      // run animation as long as distance is not met, otherwise call complete()
      if (leftRef.current > 0) {
        --leftRef.current
        boxRef.current.style.left = leftRef.current + 'px'
      } else {
        complete(() => {
          leftRef.current = 400
          startMoveRight()
        })
      }
    }
  })

  const cancel = () => {
    cancelMoveLeft()
    cancelMoveRight()
  }

  const start = () => {
    if (rightRef.current >= 0 && leftRef.current === 400) {
      startMoveRight()
    } else {
      startMoveLeft()
    }
  }

  return (
    <>
      <button onClick={start}>Start</button>
      <button onClick={cancel}>cancel</button>
      <div ref={boxRef} style={{ width: '100px', height: '100px', background: 'purple', position: 'relative' }} />
    </>
  )
}

Parameters

| Name | Type | Description | | ---------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | callback | Function | Function that will be called when the next frame is available. timestamp of requestAnimationFrame and complete function are passed as parameters. | | autoInvoke | boolean | (Optional) Determines whether the requestAnimationFrame should start when the component mounts. false by default. | | depsList | React.DependencyList | (Optional) List of dependencies used in the callback function. Pass state values that the callback function might depend on. Empty by default. |

Return Value

Returns an array with the following elements:

| Name | Type | Description | | ----- | -------- | ------------------------------------------------ | | [0] | Function | Start animation. | | [1] | Function | Cancel animation. | | [2] | Function | A function to check the status of the animation. |

useDebounce

Debounces a callback delaying its execution time since the last call.

Examples

import { useDebounce } from '@mhmdjawhar/react-hooks'
import { useState } from 'react'

export const DebounceExample: React.FC = () => {
  const [text, setText] = useState('')

  const handleTextChange = useDebounce(
    (value: string) => {
      setText(value)
    },
    500,
    [text]
  )

  const onChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    const value = event.target.value
    handleTextChange(value)
  }

  return (
    <>
      <input onChange={onChange} />
      <p>debounced text: {text}</p>
    </>
  )
}

Parameters

| Name | Type | Description | | -------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | callback | Function | Function to be debounced. | | delay | number | Debounce delay (ms) after which the callback function will be executed. | | depsList | DependencyList | (Optional) List of dependencies used in the callback function. Pass state values that the callback function might depend on. Empty by default. |

Return Value

| Name | Type | Description | | -------- | -------- | --------------------------------------- | | debounce | Function | A function that debounces the callback. |

useLocalStorage

Used to manage local storage items.

Examples

import { useLocalStorage } from '@mhmdjawhar/react-hooks'
import { useState } from 'react'

const initialValue = { firstTime: true, progress: 0 }

export const LocalStorageExample: React.FC = () => {
  const [getTutorial, setTutorial, resetTutorial] = useLocalStorage('tutorial', initialValue)

  const [state, setState] = useState(getTutorial() || initialValue)

  const handleProgressClick = () => {
    const tutorial = getTutorial()
    setTutorial({ firstTime: false, progress: tutorial ? tutorial.progress + 1 : 1 })
    setState(getTutorial())
  }

  const handleResetClick = () => {
    resetTutorial()
    setState(getTutorial())
  }

  return (
    <>
      <button onClick={handleProgressClick}>progress: {state?.progress || 0}</button>
      <button onClick={handleResetClick}>reset tutorial</button>
      <p>local Storage value: {JSON.stringify(state)}</p>
    </>
  )
}

Parameters

| Name | Type | Description | | ------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------ | | key | string | Key of the local storage item. | | initialValue | any | (Optional) Initial value of the item if it doesn't exist yet. If raw is set to true make sure initial value is a string. | | raw | boolean | (Optional) If set to true the stored value will not be JSON serialized. Defaults to false. |

Return Value

Returns an array with the following elements:

| Name | Type | Description | | ----- | -------- | ----------------------------------------- | | [0] | Function | A function that returns the stored value. | | [1] | Function | A function to update the item. | | [2] | Function | A function to remove the item. |

useMediaQuery

Listens and checks media query matches.

Examples

import { useMediaQuery } from '@mhmdjawhar/react-hooks'

export const MediaQueryExample: React.FC = () => {
  const matches = useMediaQuery('(max-width: 30em)')

  return <p>breakpoint matches? {matches ? 'true' : 'false'}</p>
}

Parameters

| Name | Type | Description | | ------------ | --------- | ----------------------------------------------------------------------- | | query | string | Media query string. | | initialValue | boolean | (Optional) Initial value of the match query state. Defaults to false. |

Return Value

| Name | Type | Description | | ------- | --------- | -------------------------------------------------------------- | | matches | boolean | true if the media query is matched, and false if it's not. |

💎 Contributions

Any Contributions are welcome!!😄

Feel free to suggest hooks that you think are useful and worth adding to this collection, and work on them if you're interested!

⚖️ License

This library is licensed under the MIT license.