use-event-listener (use-event-listener)

A React hook for managing DOM event listeners with proper cleanup.

v0.1.0

Usage

import { use-event-listener } from "@/hooks"

"use client";

import React, { useRef, useState } from "react";

import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import {
  Card,
  CardContent,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";

import { useEventListener } from "@/components/hooks/use-event-listener";

export function UseEventListenerDemo() {
  // State for window events
  const [windowMousePosition, setWindowMousePosition] = useState({
    x: 0,
    y: 0,
  });
  const [windowScroll, setWindowScroll] = useState(0);

  // State for element-specific events
  const [clickCount, setClickCount] = useState(0);
  const [isHovering, setIsHovering] = useState(false);

  // Reference for the element we want to track
  const buttonRef = useRef<HTMLButtonElement>(null);

  // Track mouse position across the window
  useEventListener({
    eventName: "mousemove",
    handler: (event) => {
      setWindowMousePosition({
        x: event.clientX,
        y: event.clientY,
      });
    },
  });

  // Track window scroll position
  useEventListener({
    eventName: "scroll",
    handler: () => {
      setWindowScroll(window.scrollY);
    },
  });

  // Track clicks on a specific element
  useEventListener<"click", HTMLButtonElement>({
    eventName: "click",
    handler: () => setClickCount((prev) => prev + 1),
    element: buttonRef,
  });

  // Track mouse enter/leave on element
  useEventListener<"mouseenter", HTMLButtonElement>({
    eventName: "mouseenter",
    handler: () => setIsHovering(true),
    element: buttonRef,
  });

  useEventListener<"mouseleave", HTMLButtonElement>({
    eventName: "mouseleave",
    handler: () => setIsHovering(false),
    element: buttonRef,
  });

  return (
    <div className="space-y-4">
      <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
        <Card className="max-w-sm w-full">
          <CardHeader>
            <CardTitle>Window Events</CardTitle>
          </CardHeader>
          <CardContent className="space-y-2">
            <p className="font-medium">Mouse Position: </p>
            <Badge variant="secondary">
              X: {windowMousePosition.x}, Y: {windowMousePosition.y}
            </Badge>
            <p className="font-medium">Scroll Position: </p>
            <Badge variant="secondary">{windowScroll}px</Badge>
          </CardContent>
        </Card>

        <Card className="max-w-sm w-full">
          <CardHeader>
            <CardTitle>Element Events</CardTitle>
          </CardHeader>
          <CardContent className="space-y-2">
            <div>
              <span className="font-medium">Click Count: </span>
              <Badge variant="secondary">{clickCount}</Badge>
            </div>
            <div>
              <span className="font-medium">Hover State: </span>
              <Badge variant={isHovering ? "default" : "secondary"}>
                {isHovering ? "Hovering" : "Not Hovering"}
              </Badge>
            </div>
          </CardContent>
          <CardFooter>
            <Button
              ref={buttonRef}
              className={`mt-2 ${isHovering ? "bg-primary-foreground" : ""}`}
            >
              Click Me
            </Button>
          </CardFooter>
        </Card>
      </div>

      <div className="text-sm text-muted-foreground">
        Try moving your mouse, scrolling, or interacting with the button above.
      </div>
    </div>
  );
}

Install

npx wkkkis-hooks add use-event-listener

Options

Name	Type	Default	Description
eventName	keyof WindowEventMap	Required	The DOM event name to listen for
handler	(event: Event) => void	Required	The callback function for the event
element	RefObject<HTMLElement> \| EventTarget	window	The element to attach the listener to
options	boolean \| AddEventListenerOptions	undefined	Options for addEventListener

Features

useEventListener provides a clean, type-safe way to manage DOM event listeners in React components with these benefits:
Automatically handles cleanup on unmount to prevent memory leaks
Preserves handler reference between renders with a ref
Type-safe event names and handler parameters
Works with window, document, or specific DOM elements
Supports all AddEventListener options

Browser Support

This hook relies on the standard DOM addEventListener API, which is supported in all modern browsers:
Chrome: Full support
Firefox: Full support
Safari: Full support
Edge: Full support
Opera: Full support

Performance Considerations

Uses useRef to avoid recreating event listeners on each render
Minimizes re-renders by not returning state
Automatic cleanup prevents memory leaks
Minimal overhead compared to direct event listeners

Best Practices & Caveats

Always provide a stable handler or use useCallback for the event handler
For element refs, ensure the element is mounted before the hook runs
For high-frequency events like mousemove or scroll, consider debouncing or throttling
TypeScript users benefit from complete type safety for events
Be cautious with passive events on touch devices for performance

Files in this hook

Source	Destination
files/use-event-listener.ts	src/hooks/use-event-listener.ts