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