Skip to content

useEventListener()

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

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

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 extends keyof WindowEventMap

KH extends "copy" | "error" | "toggle" | "abort" | "animationcancel" | "animationend" | "animationiteration" | "animationstart" | "auxclick" | "beforeinput" | "beforetoggle" | "blur" | "cancel" | "canplay" | "canplaythrough" | "change" | "click" | "close" | "compositionend" | "compositionstart" | "compositionupdate" | "contextlost" | "contextmenu" | "contextrestored" | "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 extends "change"

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

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

Example 2: Attach a button click listener

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

Example 3: Attach a document event listener

tsx
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

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

Released under the MIT License.