React - My useEventListener Hook

My useEventListener Hook is intended to manage DOM event listeners for various elements in a React application. By abstracting away the setup and cleanup of event listeners, this Hook makes it easy for me to:

• Specify an event type and callback function.
• Attach the listener to a specified element (defaulting to the window).
• Handle event listeners declaratively, so they can adapt to changing dependencies and component re-renders.

import React, { useEffect, useCallback, useMemo } from 'react'

enum EventType {
    PointerMove = 'pointermove',
    Wheel = 'wheel',
    Keyup = 'keyup',
    Keydown = 'keydown',
    PointerDown = 'pointerdown',
    PointerUp = 'pointerup',
    Resize = 'resize',
}

type EventCallbackArgType<T extends PointerEvent | WheelEvent | KeyboardEvent> =
    (e: T) => void

export const useEventListener = <
    T extends PointerEvent | WheelEvent | KeyboardEvent,
    E extends HTMLElement | Document | Window = Window,
>(
    eventType: EventType,
    callback: EventCallbackArgType<T>,
    element: E = window as unknown as E,
    dependencies: React.DependencyList = [],
    options?: AddEventListenerOptions
) => {
    const handler = useCallback(
        (e: Event) => {
            callback(e as T)
        },
        [callback]
    )

    const memoisedElement = useMemo(() => element, [element])

    useEffect(() => {
        memoisedElement.addEventListener(eventType, handler, options)
        return () =>
            memoisedElement.removeEventListener(eventType, handler, options)
    }, [eventType, memoizedElement, handler, options, ...(dependencies || [])])
}

Type Definitions:

• EventType: Enumerates common DOM event types such as pointer movements, mouse scroll (wheel) events, key presses, and window resizing.
• EventCallbackArgType: Defines the structure of the callback function, which takes a generic event type parameter (T), supporting events like PointerEvent, WheelEvent, and KeyboardEvent.

Hook Parameters:

• eventType: A specific EventType enum value that defines the event to listen for (e.g., EventType.PointerMove).
• callback: A function invoked whenever the specified event is triggered.
• element: The target element for the listener (defaulting to window), which could be an HTMLElement, Document, or Window.
• When TypeScript is trying to assign the default value (window) to a generic type E, it can't guarantee that E is always compatible with Window because E could also be HTMLElement or Document. I cast this to unknown first and then convert it to E, telling TypeScript that I'm assigning it to window and handling it as a valid E type.
• dependencies: An optional dependency array to control re-creation of the event listener if certain values change.
• I define this type dependencies as React.DependencyList, which is specifically designed for use in useEffect dependencies. This type is defined as readonly any[], but it's the standard and preferred way to handle dependency arrays in React with TypeScript.
• options: Optional AddEventListenerOptions that configure the listener (e.g., { passive: true } to improve performance when scrolling).

handler and memoizedElement:

• handler: Uses useCallback to memoize the callback, ensuring the same reference is used unless callback itself changes. This helps reduce unnecessary re-registrations of the event listener.
• memoisedElement: Uses useMemo to memoize the element to prevent re-creation across renders, which optimises the Hook’s efficiency.

Mount and cleanup:

useEffect: this manages the event listener’s lifecycle. It attaches the event listener when the component mounts or when dependencies change, and cleans up by removing it when the component unmounts or dependencies update.

Tracking Mouse Movements

This example demonstrates listening for mouse movement events, updating state based on the cursor's position on the page.

import React, { useState } from 'react'
import { useEventListener} from './useEventListener'

export const CursorTracker = () => {
    const [position, setPosition] = useState({ x: 0, y: 0 })

    useEventListener(EventType.PointerMove, (e: PointerEvent) => {
        setPosition({ x: e.clientX, y: e.clientY })
    });

    return (
        <div>
            <p>Cursor Position: X - {position.x}, Y - {position.y}</p>
        </div>
    )
}

Wheel Event on a Specific DOM Element with Passive Listener

This example demonstrates using the hook to handle a wheel event on a specific div element, with the passive option enabled to improve scroll performance.

import { useRef, useState } from 'react'
import { useEventListener, EventType } from './useEventListener'

export const WheelEvent = () => {
    const [scrollAmount, setScrollAmount] = useState(0)
    const scrollRef = useRef<HTMLDivElement>(null)

    useEventListener(
        EventType.Wheel,
        (e: WheelEvent) => {
            setScrollAmount(prev => prev + e.deltaY)
        },
        scrollRef.current,
        [],
        { passive: true }  // Passive event listener for better scroll performance
    )

    return (
        <div>
            <h2>Wheel Scroll Amount: {scrollAmount}</h2>
            <div
                ref={scrollRef}
                style={{ width: '300px', height: '200px', overflow: 'auto' }}
            >
                <p>Scroll inside this box with your mouse wheel.</p>
                <p>Scroll Amount: {scrollAmount}</p>
            </div>
        </div>
    )
}

Resize Event Listener for Window

This example demonstrates using the resize event to dynamically adjust the layout based on window size.

import { useState } from 'react'
import { useEventListener, EventType } from './useEventListener'

export const ResizeEvent = () => {
    const [windowSize, setWindowSize] = useState({
        width: window.innerWidth,
        height: window.innerHeight
    })

    useEventListener(EventType.Resize, () => {
        setWindowSize({
            width: window.innerWidth,
            height: window.innerHeight
        })
    })

    return (
        <div>
            <h2>Window Size</h2>
            <p>Width: {windowSize.width}px</p>
            <p>Height: {windowSize.height}px</p>
        </div>
    )
}

Handling Multiple Keyboard Events

You can reuse the hook for different event types, such as keyup and keydown, to handle keyboard interactions. In this case the keyup and keydown events are handled separately. The component tracks which key was pressed and whether the Shift key is pressed.

import { useState } from 'react'
import { useEventListener, EventType } from './useEventListener'

export const KeyboardEvent = () => {
    const [lastKey, setLastKey] = useState<string | null>(null)
    const [isShiftPressed, setShiftPressed] = useState(false)

    // Listening for 'keyup' event
    useEventListener(EventType.Keyup, (e: KeyboardEvent) => {
        setLastKey(e.key)
        setShiftPressed(e.shiftKey)
    })

    // Listening for 'keydown' event
    useEventListener(EventType.Keydown, (e: KeyboardEvent) => {
        setShiftPressed(e.shiftKey)
    })

    return (
        <div>
            <h2>Keyboard Event Listener</h2>
            <p>Last Key Pressed: {lastKey}</p>
            <p>Shift Key Pressed: {isShiftPressed ? 'Yes' : 'No'}</p>
        </div>
    )
}