useEventListener()

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

Defined in: hooks/dom/useEventListener.ts:55

A React hook for attaching an event listener to a target element with automatic cleanup. It supports DOM elements, window, document, and MediaQueryList, and optionally debounces the handler.

Type Parameters

KW

KW extends keyof WindowEventMap

Keys of WindowEventMap.

KH

KH extends "error" | "toggle" | "abort" | "animationcancel" | "animationend" | "animationiteration" | "animationstart" | "auxclick" | "beforeinput" | "beforematch" | "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" | "pointerrawupdate" | "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"

Keys shared by HTMLElementEventMap and SVGElementEventMap.

KM

KM extends "change"

Keys of MediaQueryListEventMap.

T

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

Type of the target element.

Parameters

eventName

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

KW | KH | KM

handler

(event) => void

The callback function to handle the event.

element?

RefObject<T>

The target element ref. Defaults to window when not provided.

options?

Options passed to addEventListener.

boolean | AddEventListenerOptions

debounce?

number

Debounce delay in milliseconds. 0 or undefined disables debouncing.

Returns

void

Examples

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

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

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

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