@use-it/event-listener

A custom React Hook that provides a declarative useEventListener.

 

This hook was inspired by Dan Abramov's
blog post
"Making setInterval Declarative with React Hooks".

I needed a way to simplify the plumbing around adding and removing an event listener
in a custom hook.
That lead to a chain of tweets
between Dan and myself.

Installation

``bash
$ npm i @use-it/event-listener
`

or

`bash
$ yarn add @use-it/event-listener
`

Usage

Here is a basic setup.

`js
useEventListener(eventName, handler, element, options);
`

$3

Here are the parameters that you can use. (\* = optional)

| Parameter | Description |
| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| eventName | The event name (string). Here is a list of common events. |
| handler | A function that will be called whenever eventName fires on element. |
| element\* | An optional element to listen on. Defaults to global (i.e., window). |
| options\* | An object { capture?: boolean, passive?: boolean, once?: boolean } to be passed to addEventListener. For advanced use cases. See MDN for details. |

$3

This hook returns nothing.

Example

Let's look at some sample code. Suppose you would like to track the mouse
position. You _could_ subscribe to mouse move events with like this.

`js
const useMouseMove = () => {
const [coords, setCoords] = useState([0, 0]);

useEffect(() => {
const handler = ({ clientX, clientY }) => {
setCoords([clientX, clientY]);
};
window.addEventListener('mousemove', handler);
return () => {
window.removeEventListener('mousemove', handler);
};
}, []);

return coords;
};
`

Here we're using useEffect to roll our own handler add/remove event listener.

useEventListener abstracts this away. You only need to care about the event name
and the handler function.

`js
const useMouseMove = () => {
const [coords, setCoords] = useState([0, 0]);

useEventListener('mousemove', ({ clientX, clientY }) => {
setCoords([clientX, clientY]);
});

return coords;
};
``

Live demo

You can view/edit the sample code above on CodeSandbox.


License

MIT Licensed

Contributors

Thanks goes to these wonderful people (emoji key):

Donavon West 🚇 ⚠️ 💡 🤔 🚧 👀 🔧 💻

Kevin Kipp 💻

Justin Hall 💻 📖

Jeow Li Huan 👀

Norman Rzepka 🤔

Beer van der Drift ⚠️ 💻

clingsoft 💻

This project follows the all-contributors specification. Contributions of any kind welcome!