React useEventListener Hook

Ever added event listeners in useEffect and forgot to clean them up? You know the drill—addEventListener in the effect, track the element ref, return a cleanup function with removeEventListener, handle all the edge cases when refs change. This free open source React useEventListener custom hook handles all that event management complexity so you can focus on your app logic instead of wrestling with cleanup and memory leaks in your React applications.

useEventListener showcase

Smart event handling with automatic cleanup:

"use client";import * as React from "react";import { toast } from "sonner";import { Button } from "@/components/ui/button";import { Badge } from "@/components/ui/badge";import { Label } from "@/components/ui/label";import { useEventListener } from "@/components/ui/shadcn-io/use-event-listener";export default function UseEventListenerDemo() {  const [keyPressed, setKeyPressed] = React.useState<string>("");    // Global keyboard event  const handleKeyDown = React.useCallback((event: KeyboardEvent) => {    setKeyPressed(event.key);    toast.info(`Key: ${event.key}`, {      description: "Global keyboard listener",    });  }, []);  // Attach event listener to window  useEventListener("keydown", handleKeyDown);  return (    <div className="p-6 max-w-sm mx-auto space-y-6">      {/* Header */}      <div className="text-center space-y-2">        <h3 className="text-lg font-semibold">Event Listener Demo</h3>        <p className="text-sm text-muted-foreground">Global keyboard event handling</p>      </div>            {/* Key Display */}      <div className="space-y-2">        <Label className="text-sm font-medium">Last Key Pressed</Label>        <div className="bg-muted rounded p-3 min-h-[48px] flex items-center justify-center">          <Badge variant={keyPressed ? "default" : "secondary"} className="font-mono text-lg px-4 py-2">            {keyPressed || "None"}          </Badge>        </div>      </div>      {/* Clear Button */}      <div className="min-h-[36px] flex items-center">        <Button          onClick={() => setKeyPressed("")}          disabled={!keyPressed}          variant="outline"          size="sm"          className="w-full text-sm h-9"        >          Clear        </Button>      </div>      {/* Instructions */}      <div className="text-center min-h-[20px] flex items-center justify-center">        <div className="text-xs text-muted-foreground">          Press any key to see it captured globally        </div>      </div>    </div>  );}

"use client"import { useEffect, useRef } from "react"import type { RefObject } from "react"import { useIsomorphicLayoutEffect } from "@/components/ui/kibo-ui/use-isomorphic-layout-effect"// MediaQueryList Event based useEventListener interfacefunction useEventListener<K extends keyof MediaQueryListEventMap>(  eventName: K,  handler: (event: MediaQueryListEventMap[K]) => void,  element: RefObject<MediaQueryList>,  options?: boolean | AddEventListenerOptions,): void// Window Event based useEventListener interfacefunction useEventListener<K extends keyof WindowEventMap>(  eventName: K,  handler: (event: WindowEventMap[K]) => void,  element?: undefined,  options?: boolean | AddEventListenerOptions,): void// Element Event based useEventListener interfacefunction useEventListener<  K extends keyof HTMLElementEventMap & keyof SVGElementEventMap,  T extends Element = K extends keyof HTMLElementEventMap    ? HTMLDivElement    : SVGElement,>(  eventName: K,  handler:    | ((event: HTMLElementEventMap[K]) => void)    | ((event: SVGElementEventMap[K]) => void),  element: RefObject<T>,  options?: boolean | AddEventListenerOptions,): void// Document Event based useEventListener interfacefunction useEventListener<K extends keyof DocumentEventMap>(  eventName: K,  handler: (event: DocumentEventMap[K]) => void,  element: RefObject<Document>,  options?: boolean | AddEventListenerOptions,): voidfunction useEventListener<  KW extends keyof WindowEventMap,  KH extends keyof HTMLElementEventMap & keyof SVGElementEventMap,  KM extends keyof MediaQueryListEventMap,  T extends HTMLElement | SVGAElement | MediaQueryList = HTMLElement,>(  eventName: KW | KH | KM,  handler: (    event:      | WindowEventMap[KW]      | HTMLElementEventMap[KH]      | SVGElementEventMap[KH]      | MediaQueryListEventMap[KM]      | Event,  ) => void,  element?: RefObject<T>,  options?: boolean | AddEventListenerOptions,) {  // Create a ref that stores handler  const savedHandler = useRef(handler)  useIsomorphicLayoutEffect(() => {    savedHandler.current = handler  }, [handler])  useEffect(() => {    // Define the listening target    const targetElement: T | Window = element?.current ?? window    if (!(targetElement && targetElement.addEventListener)) return    // Create event listener that calls handler function stored in ref    const listener: typeof handler = (event) => {      savedHandler.current(event)    }    targetElement.addEventListener(eventName, listener, options)    // Remove event listener on cleanup    return () => {      targetElement.removeEventListener(eventName, listener, options)    }  }, [eventName, element, options])}export { useEventListener }

This free open source React hook simplifies DOM event management with TypeScript support for modern JavaScript applications. Whether you're building keyboard shortcuts, scroll handlers, or interactive features in your Next.js projects, this React hook keeps your event listeners clean and reliable.

Installation

npx shadcn@latest add https://www.shadcn.io/registry/use-event-listener.json

npx shadcn@latest add https://www.shadcn.io/registry/use-event-listener.json

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/use-event-listener.json

bunx shadcn@latest add https://www.shadcn.io/registry/use-event-listener.json

Why most event listener implementations suck

Look, you could manually add and remove event listeners in useEffect, track refs, handle cleanup, and deal with changing dependencies. But after debugging the third memory leak from forgotten removeEventListener calls, you'll appreciate having this handled properly.

Most developers forget to clean up event listeners when components unmount, causing memory leaks that accumulate over time in React applications. Or they add listeners in useEffect without proper cleanup, leading to duplicate listeners on re-renders. Some handle refs incorrectly and wonder why their events don't fire in TypeScript components.

The React hook automatically manages the entire event lifecycle—attach on mount, clean up on unmount, handle ref changes, and prevent stale handler issues in Next.js projects. No more memory leaks, no more lingering listeners.

Real talk—event listeners in React are trickier than they look in JavaScript development. Refs can be null, handlers can capture stale values, and cleanup is easy to mess up. This React hook gets all the edge cases right.

This free open source React hook handles the event listener boilerplate while you focus on building features. Whether you're creating React applications, Next.js projects, or TypeScript codebases, this custom hook keeps your event management bulletproof.

Features

• Versatile targets - Attach to window, document, DOM elements, or media query lists in React applications
• Automatic cleanup - Event listeners are removed on unmount or dependency changes in TypeScript components
• Type safety - Full TypeScript support with proper event type inference for Next.js projects
• Performance optimized - Handler function is stored in ref to prevent unnecessary re-renders in JavaScript development
• Multiple overloads - Different interfaces for different event targets in React frameworks
• Modern API - Uses standard addEventListener/removeEventListener in modern React applications
• Free open source - Designed for modern React development workflows

When you'll actually use this

Real talk—this isn't for every click handler in React applications. For simple component interactions, use onClick props. But when you need global listeners, document events, or complex ref-based listening, this React hook shines in Next.js projects.

Perfect for:

• Keyboard shortcuts - Global key handlers built with TypeScript for React development
• Scroll tracking - Window or element scroll monitoring using React patterns in JavaScript applications
• Outside click detection - Close dropdowns and modals on outside clicks in React components
• Resize handling - Responsive behavior for window size changes in Next.js applications
• Visibility tracking - Detect when elements enter/leave viewport using TypeScript validation
• Mouse interactions - Track mouse movements and gestures in React frameworks
• Touch events - Mobile touch and swipe gesture handling in JavaScript development
• Media query changes - Responsive breakpoint detection for TypeScript projects

API Reference

useEventListener

The hook automatically detects the target type and provides proper TypeScript support:

// Window events (no element provided)
useEventListener("scroll", (event) => console.log(event));

// Element events (with ref)
useEventListener("click", (event) => console.log(event), elementRef);

// With options
useEventListener("scroll", handler, undefined, { passive: true });

Parameters

Common gotchas

Ref null states: The React hook waits for the ref to have a value before attaching listeners in TypeScript components. If your ref is always null, no listener gets attached in React applications.

Handler function ref storage: This prevents stale closures but means your handler always gets the latest values from your component's scope in Next.js projects. Usually what you want, but worth knowing for debugging.

Window fallback default behavior: When no element is provided, events attach to the window in JavaScript development. This is convenient for global listeners but can be surprising if you expect document events.

SSR safety handling: The React hook safely handles server-side rendering where window/document don't exist in TypeScript projects. Listeners only attach on the client side.

Performance event options: Use { passive: true } for scroll and touch events to improve performance in React components. The hook passes options directly to addEventListener.

Memory leak prevention: Unlike manual addEventListener, this hook automatically cleans up all listeners on unmount, preventing accumulating event handlers in Next.js applications.

Related hooks you will also like

Questions you might have