# @use-it/event-listener > A custom React Hook that provides a useEventListener. Latest version **0.1.7** (published 2021-11-15) · MIT license · 0 weekly downloads ## Install ```sh npm install @use-it/event-listener pnpm add @use-it/event-listener yarn add @use-it/event-listener bun add @use-it/event-listener ``` ## Health **Score 30/100 (F)** — status: abandoned. Positive: has types; esm support; no vulnerabilities; high quality score. Warnings: low downloads; pre 1.0. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 0.1.7 | | Published | 2021-11-15 | | First published | 2019-02-11 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 0 | | Unpacked size | 14.1 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 355 | | Author | donavon | | Maintainers | donavon | | Keywords | react-hooks, hooks, react, utils, lib, event-listener | ## Links - npm: https://www.npmjs.com/package/@use-it/event-listener - Repository: https://github.com/donavon/use-event-listener - Homepage: https://github.com/donavon/use-event-listener#readme - Issues: https://github.com/donavon/use-event-listener/issues - npm.io page: https://npm.io/package/@use-it/event-listener ## Alternatives - [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads - [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads - [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads - [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads - [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads ## Recent versions - 0.1.7 (latest) — 2021-11-15 - 1.0.0-beta.3 (next) — 2020-11-27 - 1.0.0-beta.2 — 2020-11-22 - 1.0.0-beta.1 — 2020-11-22 - 0.1.6 — 2020-11-19 - 0.1.5 — 2020-07-26 - 0.1.4 — 2020-07-23 - 0.1.3 — 2019-03-05 - 0.1.2 — 2019-02-11 - 0.1.1 — 2019-02-11 - 0.1.0 — 2019-02-11 - 0.0.0 — 2019-02-11 ## README # @use-it/event-listener A custom React Hook that provides a declarative useEventListener. [![npm version](https://badge.fury.io/js/%40use-it%2Fevent-listener.svg)](https://badge.fury.io/js/%40use-it%2Fevent-listener) [![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#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. [![Edit demo app on CodeSandbox](https://codesandbox.io/static/img/play-codesandbox.svg)](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! --- _Source: https://npm.io/package/@use-it/event-listener · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._