🔥 use-custom-event-listener, A Lightweight React Hook for Custom Events

Ever wished handling custom DOM events in React could be easier? Now it is!

use-custom-event-listener is a zero-dependency, TypeScript-ready React hook that gives you full control over custom events in your app — with automatic cleanup, async support, and a slick API.

Created by @marvelcodes 👏

🌟 Features

• 🎯 TypeScript support out of the box
• 🔄 Listen to one or multiple events with ease
• 🧹 Auto cleanup when your component unmounts
• ⚡️ Supports async callbacks
• 🎨 Simple and expressive API
• 📦 Zero dependencies

📦 Installation

pnpm add use-custom-event-listener

You can also use npm or yarn.

🚀 Usage

Basic Example

import {
  useCustomEventListener,
  dispatchCustomEvent
} from 'use-custom-event-listener';

function MyComponent() {
  useCustomEventListener('dataRefresh', () => {
    console.log('Data refresh event received!');
  });

  return (
    <button onClick={() => dispatchCustomEvent('dataRefresh')}>
      Refresh Data
    </button>
  );
}

Multiple Events

useCustomEventListener(['dataRefresh', 'userUpdate'], () => {
  console.log('Custom event received!');
});

Async Callback Support

useCustomEventListener('dataRefresh', async () => {
  await fetchData();
  await updateUI();
});

📘 API Reference

useCustomEventListener

A React hook for listening to one or more custom events.

useCustomEventListener(
  eventNames: string | string[],
  callback: () => Promise<void> | void
)

• eventNames: A single event name or array of names.
• callback: Function to run when the event fires (can be async).

dispatchCustomEvent
Dispatches a custom DOM event.

dispatchCustomEvent(eventNames: string | string[])

🧠 Best Practices

• ✅ Use unique, descriptive event names
• ✅ Let the hook handle cleanup, no manual work needed
• ✅ Prefer multiple event names in one hook to reduce overhead
• ✅ Lean into TypeScript for the best DX

🤝 Contributing

Pull requests welcome!
Check it out on GitHub → github.com/MarvelNwachukwu/use-custom-event-listener

📜 License

MIT © Marvellous Nwachukwu

If you’re building complex React apps that rely on event-driven logic, give this hook a try. It’s intuitive, type-safe, and refreshingly lightweight. Big props to @marvelcodes for this solid addition to the React dev toolkit. 🙌

Happy coding! 🚀