react-use-listener

Demo CodeSandbox

useListener

A powerful and flexible React hook for attaching and managing event listeners on DOM elements with built-in support for debouncing and throttling.

🚀 Features

• ✅ Declarative event listener management
• ✅ Supports debouncing and throttling
• ✅ Works with refs and direct DOM elements
• ✅ Automatic cleanup to prevent memory leaks
• ✅ Flexible options: capture, passive, once

📦 Installation

npm install react-use-listener

or

yarn add react-use-listener

🔧 Usage

Basic Example

import { useRef } from "react";
import { useListener } from "react-use-listener";

function App() {
  const buttonRef = useRef<HTMLButtonElement>(null);

  useListener(buttonRef, "click", () => {
    console.log("Button clicked!");
  });

  return <button ref={buttonRef}>Click Me</button>;
}

Using Debounce and Throttle

import { useListener } from "react-use-listener";

function SearchBox() {
  useListener(
    window,
    "resize",
    () => {
      console.log("Resized!");
    },
    { throttle: 200 }
  );

  return <input type="text" placeholder="Search..." />;
}

📜 API Reference

useListener

useListener(el, event, callback, options);

Parameters:

Parameter	Type	Description
el	EventTarget	Target element or a React ref
event	string	Event name (e.g., click, keydown)
callback	(...args: any[]) => void	Function to execute when event fires
options	Options (optional)	Additional settings (see below)

Options:

Option	Type	Default	Description
debounce	number	undefined	Delay execution after inactivity (ms)
throttle	number	undefined	Limit execution rate (ms)
enabled	boolean	true	Enable or disable the event listener
once	boolean	false	Remove listener after the first execution
capture	boolean	false	Use event capturing instead of bubbling
passive	boolean	false	Optimize performance by preventing preventDefault()

🎯 Best Practices

• Use refs for dynamically created elements to ensure proper listener management.
• Use enabled: false when the listener is not needed to avoid unnecessary event bindings.
• Prefer throttle for performance-sensitive events like scroll and resize.
• Prefer debounce for user input events like keyup and search.

🛠 Contributing

1. Clone the repository:

   git clone https://github.com/md-adil/use-listener.git

2. Install dependencies:

   cd use-listener
   npm install

3. Run tests:

   npm test

📄 License

MIT License. See LICENSE for details.