useEventListener
Overview
useEventListener owns native event subscription cleanup and calls the latest committed listener without resubscribing for callback identity changes.
Signature
function useEventListener<K extends keyof WindowEventMap>(
type: K,
listener: (event: WindowEventMap[K]) => void,
options?: UseEventListenerOptions | boolean,
): void;
function useEventListener(
target: EventListenerTarget,
type: string,
listener: (event: Event) => void,
options?: UseEventListenerOptions | boolean,
): void;Parameters
Omit target to use window, or pass an EventTarget, nullable target, or ref-like { current }. Native capture, passive, once, and signal options are supported. onError observes listener failures.
Returns
Nothing. Subscription lifetime follows the component and relevant inputs.
Behavior
The callback ref updates at commit. The native listener is replaced when the target, type, or meaningful options change and is removed with the same capture value. A thrown listener error is reported to onError and then rethrown; the subscription remains removable.
SSR / RSC
When window or the explicit target is unavailable, no subscription is created. Use in a Client Component.
Example
Composition
Combine with useThrottleFn when an event is frequent but downstream work should be limited.