@alessiofrittoli/react-hooks

React Hooks 🪝

TypeScript React utility Hooks

Table of Contents

• Getting started
• ESLint Configuration
• API Reference
  • Browser API
    • useStorage
    • useLocalStorage
    • useSessionStorage
    • useMediaQuery
    • useDarkMode
    • useIsPortrait
  • DOM API
    • useScrollBlock
    • useFocusTrap
    • useInView
  • Miscellaneous
    • useIsClient
    • useIsFirstRender
    • useUpdateEffect
    • usePagination
• Development
  • Install depenendencies
  • Build the source code
  • ESLint
  • Jest
• Contributing
• Security
• Credits

Getting started

Run the following command to start using react-hooks in your projects:

npm i @alessiofrittoli/react-hooks

or using pnpm

pnpm i @alessiofrittoli/react-hooks

ESLint Configuration

This library may define and exports hooks that requires additional ESLint configuration for your project such as useUpdateEffect.

Simply imports recommended configuration from @alessiofrittoli/react-hooks/eslint and add them to your ESLint configuration like so:

import { config as AFReactHooksEslint } from '@alessiofrittoli/react-hooks/eslint'

/** @type {import('eslint').Linter.Config[]} */
const config = [
  ...AFReactHooksEslint.recommended,
  // ... other configurations
]


export default config

API Reference

Browser API

Storage

The following storage hooks use Storage Utilities from @alessiofrittoli/web-utils adding a React oriented implementation.

useStorage

Easly handle Local or Session Storage State.

Type parameters

Parameter	Type	Default	Description
T	any	string	A custom type applied to the stored item.

Parameters

Parameter	Type	Default	Description
key	string	-	The storage item key.
initial	T	-	The storage item initial value.
type	local|session	local	(Optional) The storage API to use.

Returns

Type: [ Value<T>, SetValue<Value<T>> ]

A tuple with the stored item value or initial value and the setter function.

Usage

Importing the hooks

import {
  useStorage, useLocalStorage, useSessionStorage
} from '@alessiofrittoli/react-hooks'

Reading item value from storage

'use client'

import { useStorage } from '@alessiofrittoli/react-hooks'

type Locale = 'it' | 'en'

const storage       = 'local' // or 'session'
const defaultLocale = 'it'

export const SomeComponent: React.FC = () => {

  const [ userLocale ] = useStorage<Locale>( 'user-locale', defaultLocale, storage )

  return (
    ...
  )

}

Updating storage item value

'use client'

import { useCallback } from 'react'
import { useStorage } from '@alessiofrittoli/react-hooks'

type Locale = 'it' | 'en'

const storage       = 'local' // or 'session'
const defaultLocale = 'it'

export const LanguageSwitcher: React.FC = () => {

  const [ userLocale, setUserLocale ] = useStorage<Locale>( 'user-locale', defaultLocale, storage )

  const clickHandler = useCallback( () => {
    setUserLocale( 'en' )
  }, [ setUserLocale ] )

  return (
    ...
  )

}

Deleting storage item

'use client'

import { useCallback } from 'react'
import { useStorage } from '@alessiofrittoli/react-hooks'

type Locale = 'it' | 'en'

const storage       = 'local' // or 'session'
const defaultLocale = 'it'

export const LanguageSwitcher: React.FC = () => {

  const [ userLocale, setUserLocale ] = useStorage<Locale>( 'user-locale', defaultLocale, storage )

  const deleteHandler = useCallback( () => {
    setUserLocale( null )
    // or
    setUserLocale( undefined )
    // or
    setUserLocale( '' )
  }, [ setUserLocale ] )

  return (
    ...
  )

}

useLocalStorage

Shortcut React Hook for useStorage.

Applies the same API Reference.

useSessionStorage

Shortcut React Hook for useStorage.

Applies the same API Reference.

useMediaQuery

Get Document Media matches and listen for changes.

Parameters

Parameter	Type	Description
query	string	A string specifying the media query to parse into a MediaQueryList.

Returns

Type: boolean

• true if the document currently matches the media query list.
• false otherwise.

Usage

Check if user device prefers dark color scheme

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

const isDarkOS = useMediaQuery( '(prefers-color-scheme: dark)' )

useDarkMode

Easily manage dark mode with full respect for user device preferences.

This hook is user-oriented and built to honor system-level color scheme settings:

• If the device prefers a dark color scheme, dark mode is automatically enabled on first load.
• If the user enables/disables dark mode via a web widget, the preference is stored in localStorage under the key dark-mode.
• If the device color scheme preference changes (e.g. via OS settings), that change takes precedence and is stored for future visits.

Parameters

Parameter	Type	Description
options	UseDarkModeOptions	(Optional) Configuration object for the hook.
options.initial	boolean	(Optional) The fallback value to use if no preference is saved in localStorage. Defaults to true if the device prefers dark mode.
options.docClassNames	[dark: string, light: string]	(Optional) Array of class names to toggle on the <html> element, e.g. ['dark', 'light'].

Returns

Type: UseDarkModeOutput

An object containing utilities for managing dark mode:

• isDarkMode: boolean — Whether dark mode is currently enabled.
• isDarkOS: boolean — Whether the user's system prefers dark mode.
• toggleDarkMode: () => void — Toggles dark mode and saves the preference.
• enableDarkMode: () => void — Enables dark mode and saves the preference.
• disableDarkMode: () => void — Disables dark mode and saves the preference.

Usage

Basic usage

'use client'

import { useDarkMode } from '@alessiofrittoli/react-hooks'

export const Component: React.FC = () => {
  const { isDarkMode } = useDarkMode()

  return (
    <div>{ isDarkMode ? 'Dark mode enabled' : 'Dark mode disabled' }</div>
  )
}

Update Document class names for CSS styling

// Component.tsx
'use client'

import { useDarkMode } from '@alessiofrittoli/react-hooks'

export const Component: React.FC = () => {
  const { isDarkMode } = useDarkMode( {
    docClassNames: [ 'dark', 'light' ],
  } )

  return (
    <div>{ isDarkMode ? 'Dark mode enabled' : 'Dark mode disabled' }</div>
  )
}

/* style.css */
.light {
  color-scheme: light;
}

.dark {
  color-scheme: dark;
}

.light body
{
  color     : black;
  background: white;
}

.dark body
{
  color     : white;
  background: black;
}

Custom theme switcher

'use client'

import { useDarkMode } from '@alessiofrittoli/react-hooks'

export const ThemeSwitcher: React.FC = () => {
  const { isDarkMode, toggleDarkMode } = useDarkMode()

  return (
    <button onClick={ toggleDarkMode }>
      { isDarkMode ? '🌙' : '☀️' }
    </button>
  )
}

Sync Document theme-color for consistent browser styling

Browsers automatically apply colorization using:

<meta name='theme-color' media='(prefers-color-scheme: dark)' />

This works based on the OS preference — not your site theme. That can cause mismatches if, for example, the system is in dark mode but the user disabled dark mode via a web toggle.

To ensure consistency, useDarkMode updates these meta tags dynamically based on the actual mode.

Just make sure to define both light and dark theme-color tags in your document:

<head>
  <meta name='theme-color' media='(prefers-color-scheme: light)' content='lime'>
  <meta name='theme-color' media='(prefers-color-scheme: dark)' content='aqua'>
</head>

useIsPortrait

Check if device is portrait oriented.

React State get updated when device orientation changes.

Returns

Type: boolean

• true if the device is portrait oriented.
• false otherwise.

Usage

Check if user device is in landscape

import { useIsPortrait } from '@alessiofrittoli/react-hooks'

const isLandscape = ! useIsPortrait()

DOM API

useScrollBlock

Prevent Element overflow.

Parameters

Parameter	Type	Default	Description
target	React.RefObject<HTMLElement|null>	Document.documentElement	(Optional) The React RefObject target HTMLElement.

Returns

Type: [ () => void, () => void ]

A tuple with block and restore scroll callbacks.

Usage

Block Document Overflow

import { useScrollBlock } from '@alessiofrittoli/react-hooks'

const [ blockScroll, restoreScroll ] = useScrollBlock()

const openPopUpHandler = useCallback( () => {
  ...
  blockScroll()
}, [ blockScroll ] )

const closePopUpHandler = useCallback( () => {
  ...
  restoreScroll()
}, [ restoreScroll ] )

...

Block HTML Element Overflow

const elementRef = useRef<HTMLDivElement>( null )

const [ blockScroll, restoreScroll ] = useScrollBlock( elementRef )

const scrollBlockHandler = useCallback( () => {
  ...
  blockScroll()
}, [ blockScroll ] )

const scrollRestoreHandler = useCallback( () => {
  ...
  restoreScroll()
}, [ restoreScroll ] )

...

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.

Parameters

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.

Returns

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.

Usage

Defining the target on hook initialization

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

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 ] )

useInView

Check if the given target Element is intersecting with an ancestor Element or with a top-level document's viewport.

Parameters

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:
		- all - 1 will be used.
		- some - 0.5 will be used.
		- number
		- number[]
options.once	boolean	(Optional) By setting this to true the observer will be disconnected after the target Element enters the viewport.
options.initial	boolean	(Optional) Initial value. This value is used while server rendering then will be updated in the client based on target visibility. Default: false.
options.enable	boolean	(Optional) Defines the initial observation activity. Use the returned setEnabled to update this state. Default: true.
options.onIntersect	OnIntersectStateHandler	(Optional) A custom callback executed when target element's visibility has crossed one or more thresholds.
		This callback is awaited before any state update.
		If an error is thrown the React State update won't be fired.
		⚠️ Wrap your callback with useCallback to avoid unnecessary IntersectionObserver recreation.
options.onEnter	OnIntersectHandler	(Optional) A custom callback executed when target element's visibility has crossed one or more thresholds.
		This callback is awaited before any state update.
		If an error is thrown the React State update won't be fired.
		⚠️ Wrap your callback with useCallback to avoid unnecessary IntersectionObserver recreation.
options.onExit	OnIntersectHandler	(Optional) A custom callback executed when target element's visibility has crossed one or more thresholds.
		This callback is awaited before any state update.
		If an error is thrown the React State update won't be fired.
		⚠️ Wrap your callback with useCallback to avoid unnecessary IntersectionObserver recreation.

Returns

Type: UseInViewReturnType

An object containing:

• inView: boolean - Indicates whether the target Element is in viewport or not.
• setInView: React.Dispatch<React.SetStateAction<boolean>> - A React Dispatch SetState action that allows custom state updates.
• enabled: boolean - Indicates whether the target Element is being observed or not.
• setEnabled: React.Dispatch<React.SetStateAction<boolean>> - A React Dispatch SetState action that allows to enable/disable observation when needed.
• observer: IntersectionObserver | undefined - The IntersectionObserver instance. It could be undefined if IntersectionObserver is not available or observation is not enabled.

Usage

Basic usage

'use client'

import { useRef } from 'react'
import { useInView } from '@alessiofrittoli/react-hooks'

const UseInViewExample: React.FC = () => {

  const targetRef   = useRef<HTMLDivElement>( null )
  const { inView }  = useInView( ref )

  return (
    Array.from( Array( 6 ) ).map( ( value, index ) => (
      <div
        key={ index }
        style={ {
          height          : '50vh',
          border          : '1px solid red',
          display         : 'flex',
          alignItems      : 'center',
          justifyContent  : 'center',
        } }
      >
        <div
          ref={ index === 2 ? targetRef : undefined }
          style={ {
            width           : 150,
            height          : 150,
            borderRadius    : 12,
            display         : 'flex',
            alignItems      : 'center',
            justifyContent  : 'center',
            background      : inView ? '#51AF83' : '#201A1B',
            color           : inView ? '#201A1B' : '#FFFFFF',
          } }
        >{ index + 1 }</div>
      </div>
    ) )
  )

}

Disconnect observer after target enters the viewport

'use client'

import { useRef } from 'react'
import { useInView } from '@alessiofrittoli/react-hooks'

const OnceExample: React.FC = () => {

  const targetRef   = useRef<HTMLDivElement>( null )
  const { inView }  = useInView( targetRef, { once: true } )

  useEffect( () => {

    if ( ! inView ) return
    console.count( 'Fired only once: element entered viewport.' )

  }, [ inView ] )

  return (
    <div
      ref={ targetRef }
      style={ {
        height      : 200,
        background  : inView ? 'lime' : 'gray',
      } }
    />
  )

}

Observe target only when needed

'use client'

import { useRef } from 'react'
import { useInView } from '@alessiofrittoli/react-hooks'

const OnDemandObservation: React.FC = () => {

  const targetRef = useRef<HTMLDivElement>( null )
  const {
    inView, enabled, setEnabled
  } = useInView( targetRef, { enable: false } )

  return (
    <div>
      <button onClick={ () => setEnabled( prev => ! prev ) }>
        { enabled ? 'Disconnect observer' : 'Observe' }
      </button>
      <div
        ref={ targetRef }
        style={ {
          height      : 200,
          marginTop   : 50,
          background  : inView ? 'lime' : 'gray',
        } }
      />
    </div>
  )

}

Execute custom callback when intersection occurs

'use client'

import { useRef } from 'react'
import { useInView, type OnIntersectStateHandler } from '@alessiofrittoli/react-hooks'


const AsyncStartExample: React.FC = () => {

  const targetRef = useRef<HTMLDivElement>( null )
  const onIntersect   = useCallback<OnIntersectStateHandler>( async ( { entry, isEntering } ) => {

    if ( isEntering ) {
      console.log( 'Delaying state update...' )
      await new Promise( resolve => setTimeout( resolve, 1000 ) ) // Simulate delay
      console.log( 'Async task completed. `inView` will now be updated.' )
      return
    }
    
    console.log( 'Delaying state update...' )
    await new Promise( resolve => setTimeout( resolve, 1000 ) ) // Simulate delay
    console.log( 'Async task completed. `inView` will now be updated.' )
  
  }, [] )

  const { inView } = useInView( targetRef, { onIntersect } )

  return (
    <div
      ref={ targetRef }
      style={ {
        height      : 200,
        background  : inView ? 'lime' : 'gray',
      } }
    />
  )
}

Execute custom callback when onEnter and onExit

'use client'

import { useRef } from 'react'
import { useInView, type OnIntersectHandler } from '@alessiofrittoli/react-hooks'


const AsyncStartExample: React.FC = () => {

  const targetRef = useRef<HTMLDivElement>( null )
  const onEnter = useCallback<OnIntersectHandler>( async ( { entry } ) => {
    console.log( 'In viewport - ', entry )
  }, [] )
  const onExit = useCallback<OnIntersectHandler>( async ( { entry } ) => {
    console.log( 'Exited viewport - ', entry )
  }, [] )

  const { inView } = useInView( targetRef, { onEnter, onExit } )

  return (
    <div
      ref={ targetRef }
      style={ {
        height      : 200,
        background  : inView ? 'lime' : 'gray',
      } }
    />
  )
}

Miscellaneous

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.

Returns

Type: boolean

• true if the React Hook or Component is running in a browser environment.
• false otherwise.

Usage

Basic usage

'use client'

import { useIsClient } from '@alessiofrittoli/react-hooks'

export const ClientComponent: React.FC = () => {

  const isClient = useIsClient()

  return (
    <div>Running { ! isClient ? 'server' : 'client' }-side</div>
  )

}

useIsFirstRender

Check if is first React Hook/Component render.

Returns

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.

Usage

Basic usage

'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>
  )

}

useUpdateEffect

Modified version of useEffect that skips the first render.

Parameters

Parameter	Type	Description
effect	React.EffectCallback	Imperative function that can return a cleanup function.
deps	React.DependencyList	If present, effect will only activate if the values in the list change.

Usage

Basic usage

'use client'

import { useEffect, useState } from 'react'
import { useUpdateEffect } from '@alessiofrittoli/react-hooks'

export const ClientComponent: React.FC = () => {

  const [ count, setCount ] = useState( 0 )

  useEffect( () => {
    const intv = setInterval( () => {
      setCount( prev => prev + 1 )
    }, 1000 )
    return () => clearInterval( intv )
  }, [] )

  useEffect( () => {
    console.log( 'useEffect', count ) // starts from 0
    return () => {
      console.log( 'useEffect - clean up', count ) // starts from 0
    }
  }, [ count ] )

  useUpdateEffect( () => {
    console.log( 'useUpdateEffect', count ) // starts from 1
    return () => {
      console.log( 'useUpdateEffect - clean up', count ) // starts from 1
    }
  }, [ count ] )

  return (
    <div>{ count }</div>
  )

}

usePagination

Get pagination informations based on the given options.

This hook memoize the returned result of the paginate function imported from @alessiofrittoli/math-utils.

See paginate function Documentation for more information about it.

Development

Install depenendencies

npm install

or using pnpm

pnpm i

Build the source code

Run the following command to test and build code for distribution.

pnpm build

ESLint

warnings / errors check.

pnpm lint

Jest

Run all the defined test suites by running the following:

# Run tests and watch file changes.
pnpm test:watch

# Run tests in a CI environment.
pnpm test:ci

• See package.json file scripts for more info.

Run tests with coverage.

An HTTP server is then started to serve coverage files from ./coverage folder.

⚠️ You may see a blank page the first time you run this command. Simply refresh the browser to see the updates.

test:coverage:serve

Contributing

Contributions are truly welcome!

Please refer to the Contributing Doc for more information on how to start contributing to this project.

Help keep this project up to date with GitHub Sponsor.

Security

If you believe you have found a security vulnerability, we encourage you to responsibly disclose this and NOT open a public issue. We will investigate all legitimate reports. Email [e-mail] to disclose any security vulnerabilities.

Made with ☕

Alessio Frittoli https://alessiofrittoli.it | [e-mail]