useEventListener()

useEventListener<KW, KH, KM, T>(eventName, handler, element?, options?, debounce?): void

Defined in: src/hooks/dom/useEventListener.ts:59

A custom React hook for attaching an event listener to a target element with automatic cleanup. This hook is useful for adding event listeners to DOM elements or the window object. It also supports optional debouncing to limit how often the handler is invoked.

Type Parameters

KW

KW extends keyof WindowEventMap

KH

KH extends "error" | "toggle" | "abort" | "animationcancel" | "animationend" | "animationiteration" | "animationstart" | "auxclick" | "beforeinput" | "beforetoggle" | "blur" | "cancel" | "canplay" | "canplaythrough" | "change" | "click" | "close" | "compositionend" | "compositionstart" | "compositionupdate" | "contextlost" | "contextmenu" | "contextrestored" | "copy" | "cuechange" | "cut" | "dblclick" | "drag" | "dragend" | "dragenter" | "dragleave" | "dragover" | "dragstart" | "drop" | "durationchange" | "emptied" | "ended" | "focus" | "focusin" | "focusout" | "formdata" | "gotpointercapture" | "input" | "invalid" | "keydown" | "keypress" | "keyup" | "load" | "loadeddata" | "loadedmetadata" | "loadstart" | "lostpointercapture" | "mousedown" | "mouseenter" | "mouseleave" | "mousemove" | "mouseout" | "mouseover" | "mouseup" | "paste" | "pause" | "play" | "playing" | "pointercancel" | "pointerdown" | "pointerenter" | "pointerleave" | "pointermove" | "pointerout" | "pointerover" | "pointerup" | "progress" | "ratechange" | "reset" | "resize" | "scroll" | "scrollend" | "securitypolicyviolation" | "seeked" | "seeking" | "select" | "selectionchange" | "selectstart" | "slotchange" | "stalled" | "submit" | "suspend" | "timeupdate" | "touchcancel" | "touchend" | "touchmove" | "touchstart" | "transitioncancel" | "transitionend" | "transitionrun" | "transitionstart" | "volumechange" | "waiting" | "webkitanimationend" | "webkitanimationiteration" | "webkitanimationstart" | "webkittransitionend" | "wheel" | "fullscreenchange" | "fullscreenerror"

KM

KM extends "change"

T

T extends typeof globalThis | Document | HTMLElement | MediaQueryList | SVGElement = HTMLElement

The type of the event object.

Parameters

eventName

The name of the event to listen for (e.g., 'click', 'keydown').

KW | KH | KM

handler

(event) => void

The callback function to handle the event. Receives the event object as a parameter.

element?

RefObject<T>

The target element to attach the event listener to. Defaults to globalThis if not provided.

options?

Additional options to pass to addEventListener. Such as capture or once, etc.

boolean | AddEventListenerOptions

debounce?

number

The debounce delay in milliseconds. Defaults to 0ms (no debounce).

Returns

void

Examples

Example 1: Attach a window event listener with debounce

useEventListener('resize', () => {
  console.log('Window resized!');
}, undefined, undefined, 300);

Example 2: Attach a button click listener

const buttonRef = useRef<HTMLButtonElement>(null);
useEventListener('click', () => {
  console.log('Button clicked!');
}, buttonRef);

Example 3: Attach a document event listener

const documentRef = useRef<Document>(document);
useEventListener('keydown', (event) => {
  console.log('Key pressed:', event.key);
}, documentRef, { capture: true });

Example 4: Attach a media query change listener

const mediaQueryListRef = useRef(window.matchMedia('(max-width: 600px)'));
useEventListener(
  'change',
  (event) => {
    console.log('Media query matches:', event.matches);
  },
  mediaQueryListRef
);