useEventListener

Events & gestures

A React hook for adding event listeners to DOM elements with automatic cleanup

Install

$ npm install @usefy/use-event-listener

Quick start

useEventListener.tsx

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

function WindowResizeTracker() {
  const [size, setSize] = useState({ width: 0, height: 0 });

  useEventListener("resize", () => {
    setSize({ width: window.innerWidth, height: window.innerHeight });
  });

  return (
    <div>
      Window size: {size.width} × {size.height}
    </div>
  );
}

API reference

`useEventListener(eventName, handler, element?, options?)`

A hook that adds an event listener to the specified target.

Parameters

Parameter	Type	Description
`eventName`	`string`	The event type to listen for (e.g., "click", "resize")
`handler`	`(event: Event) => void`	Callback function called when the event fires
`element`	`EventTargetType`	Target element (defaults to window)
`options`	`UseEventListenerOptions`	Configuration options

Options

Option	Type	Default	Description
`enabled`	`boolean`	`true`	Whether the event listener is active
`capture`	`boolean`	`false`	Use event capture phase instead of bubble
`passive`	`boolean`	`undefined`	Use passive event listener for performance
`once`	`boolean`	`false`	Handler is invoked once and then removed

Supported Target Types

type EventTargetType<T extends HTMLElement = HTMLElement> =
  | Window // window object
  | Document // document object
  | HTMLElement // any HTML element
  | React.RefObject<T | null> // React ref
  | null // no listener
  | undefined; // defaults to window

Returns

void

Go deeper

This page is the quick reference. For every example, prop, and edge case, read the full README — or open Storybook to change props live.

Full README →Open in Storybook →