@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
$ npm i @use-it/event-listener
or
$ yarn add @use-it/event-listener
Usage
Here is a basic setup.
useEventListener(eventName, handler, element, options);
Parameters
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. |
Return
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.
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.
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):
This project follows the all-contributors specification. Contributions of any kind welcome!
