Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/donavon/use-event-listener
A custom React Hook that provides a declarative useEventListener
https://github.com/donavon/use-event-listener
event-listener hooks react reactjs
Last synced: 9 days ago
JSON representation
A custom React Hook that provides a declarative useEventListener
- Host: GitHub
- URL: https://github.com/donavon/use-event-listener
- Owner: donavon
- License: mit
- Created: 2019-02-11T04:58:29.000Z (over 5 years ago)
- Default Branch: develop
- Last Pushed: 2023-07-24T11:43:53.000Z (11 months ago)
- Last Synced: 2024-05-17T18:03:16.879Z (about 1 month ago)
- Topics: event-listener, hooks, react, reactjs
- Language: JavaScript
- Homepage:
- Size: 712 KB
- Stars: 355
- Watchers: 7
- Forks: 35
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Lists
- awesome-github-star - use-event-listener
- awesome - use-event-listener - A custom React Hook that provides a declarative useEventListener (JavaScript)
README
# @use-it/event-listener
A custom React Hook that provides a declarative useEventListener.
[](https://badge.fury.io/js/%40use-it%2Fevent-listener) [](#contributors)
This hook was inspired by [Dan Abramov](https://github.com/gaearon)'s
blog post
["Making setInterval Declarative with React Hooks"](https://overreacted.io/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](https://twitter.com/donavon/status/1093612936621379584)
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);
```
### Parameters
Here are the parameters that you can use. (\* = optional)
| Parameter | Description |
| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eventName` | The event name (string). Here is a list of [common events](https://developer.mozilla.org/en-US/docs/Web/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](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) 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.
```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.
[](https://codesandbox.io/s/k38lyx2q9o)
## License
**[MIT](LICENSE)** Licensed
## Contributors
Thanks goes to these wonderful people ([emoji key](https://github.com/all-contributors/all-contributors#emoji-key)):
Donavon West
🚇 ⚠️ 💡 🤔 🚧 👀 🔧 💻
Kevin Kipp
💻
Justin Hall
💻 📖
Jeow Li Huan
👀
Norman Rzepka
🤔
Beer van der Drift
⚠️ 💻
clingsoft
💻
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!